mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-09-22 02:46:39 +00:00
7a01af2791
Some checks failed
CodeQL Advanced / Analyze (actions) (push) Has been cancelled
CodeQL Advanced / Analyze (python) (push) Has been cancelled
Vulnerability Scan / Detect changes (push) Has been cancelled
Vulnerability Scan / pip-audit (push) Has been cancelled
Check Documentation Broken Links / Check broken links (push) Has been cancelled
Nightly Canary Release / Check for new commits (push) Has been cancelled
Nightly Canary Release / Build nightly packages (push) Has been cancelled
Nightly Canary Release / Publish nightly to PyPI (push) Has been cancelled
260 lines
11 KiB
Plaintext
260 lines
11 KiB
Plaintext
---
|
|
title: CrewAI Tracing
|
|
description: CrewAI AMP 플랫폼을 사용한 CrewAI Crews 및 Flows의 내장 추적
|
|
icon: magnifying-glass-chart
|
|
mode: "wide"
|
|
---
|
|
|
|
# CrewAI 내장 추적 (Built-in Tracing)
|
|
|
|
CrewAI는 Crews와 Flows를 실시간으로 모니터링하고 디버깅할 수 있는 내장 추적 기능을 제공합니다. 이 가이드는 CrewAI의 통합 관측 가능성 플랫폼을 사용하여 **Crews**와 **Flows** 모두에 대한 추적을 활성화하는 방법을 보여줍니다.
|
|
|
|
> **CrewAI Tracing이란?** CrewAI의 내장 추적은 agent 결정, 작업 실행 타임라인, 도구 사용, LLM 호출을 포함한 AI agent에 대한 포괄적인 관측 가능성을 제공하며, 모두 [CrewAI AMP 플랫폼](https://app.crewai.com)을 통해 액세스할 수 있습니다. 추적은 [텔레메트리](/ko/telemetry)와 별도로 관리됩니다.
|
|
|
|
|
|
|
|
## 사전 요구 사항
|
|
|
|
CrewAI 추적을 사용하기 전에 다음이 필요합니다:
|
|
|
|
1. **CrewAI AMP 계정**: [app.crewai.com](https://app.crewai.com)에서 무료 계정에 가입하세요
|
|
2. **CLI 인증**: CrewAI CLI를 사용하여 로컬 환경을 인증하세요
|
|
|
|
```bash
|
|
crewai login
|
|
```
|
|
|
|
## 설정 지침
|
|
|
|
### 1단계: CrewAI AMP 계정 생성
|
|
|
|
[app.crewai.com](https://app.crewai.com)을 방문하여 무료 계정을 만드세요. 이를 통해 추적, 메트릭을 보고 crews를 관리할 수 있는 CrewAI AMP 플랫폼에 액세스할 수 있습니다.
|
|
|
|
### 2단계: CrewAI CLI 설치 및 인증
|
|
|
|
아직 설치하지 않았다면 CLI 도구와 함께 CrewAI를 설치하세요:
|
|
|
|
```bash
|
|
uv add 'crewai[tools]'
|
|
```
|
|
|
|
그런 다음 CrewAI AMP 계정으로 CLI를 인증하세요:
|
|
|
|
```bash
|
|
crewai login
|
|
```
|
|
|
|
이 명령은 다음을 수행합니다:
|
|
|
|
1. 브라우저에서 인증 페이지를 엽니다
|
|
2. 장치 코드를 입력하라는 메시지를 표시합니다
|
|
3. CrewAI AMP 계정으로 로컬 환경을 인증합니다
|
|
4. 로컬 개발을 위한 추적 기능을 활성화합니다
|
|
|
|
### 3단계: Crew에서 추적 활성화
|
|
|
|
`tracing` 매개변수를 `True`로 설정하여 Crew에 대한 추적을 활성화할 수 있습니다:
|
|
|
|
```python
|
|
from crewai import Agent, Crew, Process, Task
|
|
from crewai_tools import SerperDevTool
|
|
|
|
# Define your agents
|
|
researcher = Agent(
|
|
role="Senior Research Analyst",
|
|
goal="Uncover cutting-edge developments in AI and data science",
|
|
backstory=\"\"\"You work at a leading tech think tank.
|
|
Your expertise lies in identifying emerging trends.
|
|
You have a knack for dissecting complex data and presenting actionable insights.\"\"\",
|
|
verbose=True,
|
|
tools=[SerperDevTool()],
|
|
)
|
|
|
|
writer = Agent(
|
|
role="Tech Content Strategist",
|
|
goal="Craft compelling content on tech advancements",
|
|
backstory=\"\"\"You are a renowned Content Strategist, known for your insightful and engaging articles.
|
|
You transform complex concepts into compelling narratives.\"\"\",
|
|
verbose=True,
|
|
)
|
|
|
|
# Create tasks for your agents
|
|
research_task = Task(
|
|
description=\"\"\"Conduct a comprehensive analysis of the latest advancements in AI in 2024.
|
|
Identify key trends, breakthrough technologies, and potential industry impacts.\"\"\",
|
|
expected_output="Full analysis report in bullet points",
|
|
agent=researcher,
|
|
)
|
|
|
|
writing_task = Task(
|
|
description=\"\"\"Using the insights provided, develop an engaging blog
|
|
post that highlights the most significant AI advancements.
|
|
Your post should be informative yet accessible, catering to a tech-savvy audience.\"\"\",
|
|
expected_output="Full blog post of at least 4 paragraphs",
|
|
agent=writer,
|
|
)
|
|
|
|
# Enable tracing in your crew
|
|
crew = Crew(
|
|
agents=[researcher, writer],
|
|
tasks=[research_task, writing_task],
|
|
process=Process.sequential,
|
|
tracing=True, # Enable built-in tracing
|
|
verbose=True
|
|
)
|
|
|
|
# Execute your crew
|
|
result = crew.kickoff()
|
|
```
|
|
|
|
### 4단계: Flow에서 추적 활성화
|
|
|
|
마찬가지로 CrewAI Flows에 대한 추적을 활성화할 수 있습니다:
|
|
|
|
```python
|
|
from crewai.flow.flow import Flow, listen, start
|
|
from pydantic import BaseModel
|
|
|
|
class ExampleState(BaseModel):
|
|
counter: int = 0
|
|
message: str = ""
|
|
|
|
class ExampleFlow(Flow[ExampleState]):
|
|
def __init__(self):
|
|
super().__init__(tracing=True) # Enable tracing for the flow
|
|
|
|
@start()
|
|
def first_method(self):
|
|
print("Starting the flow")
|
|
self.state.counter = 1
|
|
self.state.message = "Flow started"
|
|
return "continue"
|
|
|
|
@listen("continue")
|
|
def second_method(self):
|
|
print("Continuing the flow")
|
|
self.state.counter += 1
|
|
self.state.message = "Flow continued"
|
|
return "finish"
|
|
|
|
@listen("finish")
|
|
def final_method(self):
|
|
print("Finishing the flow")
|
|
self.state.counter += 1
|
|
self.state.message = "Flow completed"
|
|
|
|
# Create and run the flow with tracing enabled
|
|
flow = ExampleFlow(tracing=True)
|
|
result = flow.kickoff()
|
|
```
|
|
|
|
### 5단계: CrewAI AMP 대시보드에서 추적 보기
|
|
|
|
추적은 인증된 내보내기 또는 명시적으로 동의한 익명 업로드가 성공한 경우에만 업로드됩니다. 로컬 버퍼가 삭제된 실행에는 업로드된 추적이 없습니다.
|
|
계정에 연결된 추적은 [CrewAI AMP 대시보드의 Traces 탭](https://app.crewai.com/crewai_plus/trace_batches)에서 agent 상호 작용, 도구 사용 및 LLM 호출을 확인하세요.
|
|
|
|
|
|
### 대안: 환경 변수 구성
|
|
|
|
환경 변수를 설정하여 전역적으로 추적을 활성화할 수도 있습니다:
|
|
|
|
```bash
|
|
export CREWAI_TRACING_ENABLED=true
|
|
```
|
|
|
|
또는 `.env` 파일에 추가하세요:
|
|
|
|
```env
|
|
CREWAI_TRACING_ENABLED=true
|
|
```
|
|
|
|
이 환경 변수가 설정되면 `tracing=True`를 명시적으로 설정하지 않아도 모든 Crews와 Flows에 자동으로 추적이 활성화됩니다.
|
|
|
|
## 첫 실행 후 추적 보기
|
|
|
|
Crew 또는 Flow를 처음 실행하면 대화형 터미널에서 다음을 물을 수 있습니다:
|
|
|
|
```text
|
|
Share this execution trace with CrewAI? [y/N]
|
|
```
|
|
|
|
버퍼에 저장된 추적을 CrewAI에 업로드하려면 **yes**를 선택하세요. 추적에는
|
|
프롬프트, 입력, 출력이 포함될 수 있습니다. 거절하거나 시간이 초과되거나
|
|
대화형 동의 프롬프트 없이 실행하면 버퍼가 삭제됩니다. 나중에
|
|
`crewai traces enable` 또는 `crewai traces disable`을 사용하거나 Crew 또는
|
|
Flow에서 `tracing`을 설정하여 추적 설정을 변경할 수 있습니다.
|
|
|
|
### 로컬 버퍼링 및 인증된 내보내기
|
|
|
|
첫 실행에서 수집한 추적은 저장된 로그인 자격 증명이 있어도 공유에 동의할
|
|
때까지 프로세스 메모리에 보관됩니다. 인증되지 않은 추적도 같은 동의 절차를
|
|
사용합니다. 동의하기 전에는 CrewAI가 업로드 권한을 요청하거나 실행 span을
|
|
전송하지 않습니다.
|
|
|
|
버퍼는 최대 **1,000개의 span**과 **8 MiB의 인코딩된 OTLP 데이터**를
|
|
보관합니다. `CREWAI_EPHEMERAL_TRACE_MAX_SPANS`와
|
|
`CREWAI_EPHEMERAL_TRACE_MAX_BYTES`를 양의 정수로 설정하여 한도를 조정할
|
|
수 있습니다. 한도를 초과하면 가장 오래된 span부터 삭제하며, 개별 span이
|
|
바이트 한도보다 크면 해당 span을 삭제합니다. 공유하거나 폐기한 후에는
|
|
버퍼를 비웁니다.
|
|
|
|
추적이 활성화되고 자격 증명을 사용할 수 있으면 CrewAI는 CLI 로그인,
|
|
`CREWAI_USER_PAT` 또는 플랫폼 통합 자격 증명을 AMP에서 실행별 권한으로
|
|
교환합니다. 그런 다음 해당 권한을 사용하여 OpenTelemetry span을 Wharf로
|
|
직접 내보냅니다. 유효하지 않은 자격 증명으로는 익명 업로드로 전환하지 않습니다.
|
|
|
|
### 호스팅된 실행 세션
|
|
|
|
호스트는 `crewai.telemetry.tracing`의 `telemetry_session`으로 실행을 감쌀
|
|
수 있습니다. 세션은 CrewAI 수명 주기 이벤트를 사용하여 span을 생성하고
|
|
종료하며 타임스탬프, 부모 관계, HITL 일시 중지/재개 링크를 유지합니다.
|
|
`providers=`에 기존 공급자를 전달하면 호스트의 tracer와 로깅 통합을
|
|
유지할 수 있습니다. `processors=`로 span 프로세서를 전달하고
|
|
`log_emitter=`로 호스트 로깅 콜백을 전달할 수 있습니다. 이러한 통합에서
|
|
데이터 마스킹은 호스트가 담당합니다.
|
|
각 세션은 자체 추적 수명 주기를 관리하며 애플리케이션의 전역
|
|
OpenTelemetry 공급자를 변경하지 않습니다.
|
|
|
|
## 추적 보기
|
|
|
|
### CrewAI AMP 대시보드 액세스
|
|
|
|
1. [app.crewai.com](https://app.crewai.com)을 방문하여 계정에 로그인하세요
|
|
2. 프로젝트 대시보드로 이동하세요
|
|
3. **Traces** 탭을 클릭하여 실행 세부 정보를 확인하세요
|
|
|
|
### 추적에서 볼 수 있는 내용
|
|
|
|
CrewAI 추적은 다음에 대한 포괄적인 가시성을 제공합니다:
|
|
|
|
- **Agent 결정**: agent가 작업을 통해 어떻게 추론하고 결정을 내리는지 확인하세요
|
|
- **작업 실행 타임라인**: 작업 시퀀스 및 종속성의 시각적 표현
|
|
- **도구 사용**: 어떤 도구가 호출되고 그 결과를 모니터링하세요
|
|
- **LLM 호출**: 프롬프트 및 응답을 포함한 모든 언어 모델 상호 작용을 추적하세요
|
|
- **성능 메트릭**: 실행 시간, 토큰 사용량 및 비용
|
|
- **오류 추적**: 세부 오류 정보 및 스택 추적
|
|
|
|
### 추적 기능
|
|
|
|
- **실행 타임라인**: 실행의 다양한 단계를 클릭하여 확인하세요
|
|
- **세부 로그**: 디버깅을 위한 포괄적인 로그에 액세스하세요
|
|
- **성능 분석**: 실행 패턴을 분석하고 성능을 최적화하세요
|
|
- **내보내기 기능**: 추가 분석을 위해 추적을 다운로드하세요
|
|
|
|
### 인증 문제
|
|
|
|
인증 문제가 발생하는 경우:
|
|
|
|
1. 로그인되어 있는지 확인하세요: `crewai login`
|
|
2. 인터넷 연결을 확인하세요
|
|
3. [app.crewai.com](https://app.crewai.com)에서 계정을 확인하세요
|
|
|
|
### 추적이 나타나지 않음
|
|
|
|
대시보드에 추적이 표시되지 않는 경우:
|
|
|
|
1. Crew/Flow에서 `tracing=True`가 설정되어 있는지 확인하세요
|
|
2. 환경 변수를 사용하는 경우 `CREWAI_TRACING_ENABLED=true`인지 확인하세요
|
|
3. 인증된 내보내기의 경우 CLI 로그인, `CREWAI_USER_PAT` 또는 플랫폼 통합 자격 증명을 확인하세요. 익명으로 공유하려면 동의 프롬프트에서 명시적으로 동의하세요. 로그인은 필요하지 않습니다
|
|
4. crew/flow가 실행되었고 추적 내보내기가 성공했는지 확인하세요. 동의를 거절하거나 시간이 초과되거나 대화형 동의 프롬프트 없이 실행하면 로컬 버퍼가 업로드되지 않고 삭제됩니다
|