> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# CrewAI Tracing
> CrewAI AMP 플랫폼을 사용한 CrewAI Crews 및 Flows의 내장 추적
# 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 theme={null}
crewai login
```
## 설정 지침
### 1단계: CrewAI AMP 계정 생성
[app.crewai.com](https://app.crewai.com)을 방문하여 무료 계정을 만드세요. 이를 통해 추적, 메트릭을 보고 crews를 관리할 수 있는 CrewAI AMP 플랫폼에 액세스할 수 있습니다.
### 2단계: CrewAI CLI 설치 및 인증
아직 설치하지 않았다면 CLI 도구와 함께 CrewAI를 설치하세요:
```bash theme={null}
uv add 'crewai[tools]'
```
그런 다음 CrewAI AMP 계정으로 CLI를 인증하세요:
```bash theme={null}
crewai login
```
이 명령은 다음을 수행합니다:
1. 브라우저에서 인증 페이지를 엽니다
2. 장치 코드를 입력하라는 메시지를 표시합니다
3. CrewAI AMP 계정으로 로컬 환경을 인증합니다
4. 로컬 개발을 위한 추적 기능을 활성화합니다
### 3단계: Crew에서 추적 활성화
`tracing` 매개변수를 `True`로 설정하여 Crew에 대한 추적을 활성화할 수 있습니다:
```python theme={null}
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 theme={null}
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 theme={null}
export CREWAI_TRACING_ENABLED=true
```
또는 `.env` 파일에 추가하세요:
```env theme={null}
CREWAI_TRACING_ENABLED=true
```
이 환경 변수가 설정되면 `tracing=True`를 명시적으로 설정하지 않아도 모든 Crews와 Flows에 자동으로 추적이 활성화됩니다.
## 첫 실행 후 추적 보기
Crew 또는 Flow를 처음 실행하면 대화형 터미널에서 다음을 물을 수 있습니다:
```text theme={null}
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가 실행되었고 추적 내보내기가 성공했는지 확인하세요. 동의를 거절하거나 시간이 초과되거나 대화형 동의 프롬프트 없이 실행하면 로컬 버퍼가 업로드되지 않고 삭제됩니다