> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

本文介绍如何基于 OpenTelemetry 协议将 CrewAI 运行过程的 Trace 数据自动上报到扣子罗盘。 
## 功能介绍 {#bf8f246f}
[CrewAI](https://github.com/crewAIInc/crewAI) 是一个用于自主编排 AI 应用的框架，通过与 OpenTelemetry 集成，能够自动捕获应用程序在调用大模型时的关键操作和性能指标，并将这些信息作为 Trace 数据上报到扣子罗盘，完成可视化分析。本集成方案适用于需要监控 CrewAI 调用大模型的过程、分析 AI 应用性能或排查 Agent 执行问题的场景。
本文以 Python SDK 为例，介绍如何通过 OpenTelemetry  SDK 将应用程序的 Trace 数据上报至扣子罗盘平台，从而实现对应用程序性能和行为的高效监控与分析。
## 准备工作 {#b6f8ffe4}
使用 OpenTelemetry Python SDK 前，需要先安装 Python SDK 以及相关的依赖库。 

1. 安装 Python SDK。 
   OpenTelemetry Python SDK 要求 Python 3.9 或以上版本。你可以通过如下方法查看 Python 版本 。 
   ```Python
   # 查看 Python 版本   
   python --version 
    
   # 回显信息显示已安装 3.9.2 版本 
   Python 3.9.2
   ```

2. 安装依赖库。 
   安装 Python 依赖库，分别用于调用 AI 模型、对调用过程进行可观测性管理以及将 Trace 数据导出到后端系统。 
   ```Python
   pip install openai
   pip install opentelemetry-sdk
   pip install opentelemetry-exporter-otlp
   pip install openinference-instrumentation-crewai
   pip install openinference-instrumentation-litellm
   pip install crewai
   ```


## 配置环境变量  {#1d55a2b8}
在上报 Trace 数据前，你需要正确配置 OpenTelemetry 的环境变量，以确保 CrewAI 应用能够正常调用 OpenAI 模型，并能正确发送 Trace 数据到指定的扣子罗盘空间中。环境变量配置格式及说明如下： 
```Python
OTEL_EXPORTER_OTLP_HEADERS=cozeloop-workspace-id={CozeLoop空间ID},Authorization=Bearer {个人访问令牌或服务访问令牌}
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.coze.cn/v1/loop/opentelemetry/v1/traces
OPENAI_BASE_URL=***
OPENAI_API_KEY=***
```

<!-- @cols-width: 322,595 -->
| | | \
|**环境变量** |**说明** |
|---|---|
| | | \
|OTEL_EXPORTER_OTLP_HEADERS  |设置上报数据时所需的扣子罗盘认证信息和工作空间标识。包括如下参数：  |\
| | |\
| |* cozeloop-workspace-id：配置为扣子罗盘工作空间 ID。获取步骤，请参考[获取扣子罗盘工作空间 ID](/cozeloop/get_workspace_id_and_token#01dede13)。 |\
| |* Authorization：配置为扣子罗盘的个人访问令牌或服务访问令牌。获取步骤，请参考[配置个人访问令牌](/cozeloop/authentication-for-sdk#05d27a86)、[配置服务访问令牌](/cozeloop/authentication-for-sdk#83f924a1)。 |
| | | \
|OTEL_EXPORTER_OTLP_TRACES_ENDPOINT  |指定 OpenTelemetry Trace 数据的上报地址，固定为 `https://api.coze.cn/v1/loop/opentelemetry/v1/traces`。  |
| | | \
|OPENAI_BASE_URL |配置 OpenAI 模型的服务地址。 |\
| | |\
| |* 推荐使用方舟模型，其 BASE_URL 固定为 `https://ark.cn-beijing.volces.com/api/v3`。 |\
| |* 使用其他 OpenAI 模型时，配置为其对应的 BASE_URL 即可。 |
| | | \
|OPENAI_API_KEY |配置 OpenAI 模型的 API Key。 |\
| | |\
| |* 推荐使用方舟模型，其 API Key 获取步骤，请参考 [API Key 管理](https://www.volcengine.com/docs/82379/1361424)。 |\
| |* 使用其他 OpenAI 模型时，配置为其对应的 API Key 即可。 |

## 上报 Trace  {#c4789068}
完成上述配置后，你可以调用 OpenAI 模型开展 AI 对话，并通过 OpenTelemetry Python SDK 上报 Trace 数据到扣子罗盘。以下示例将分别展示自动上报 Trace 数据与上报自定义 Span 节点数据的具体实现方式。
### 自动上报 {#70858454}
在本示例中，使用 CrewAI 框架调用火山方舟的 doubao-1-5-vision-pro-32k-250115 模型完成 HTML 代码生成任务，并通过 OpenTelemetry SDK 自动收集和上报 OpenAI 模型执行过程中的 Trace 数据到扣子罗盘，包括 LLM 调用、Agent 执行过程、任务生命周期等数据，从而实现对 AI 模型调用过程的全面监控和分析。
```Python
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    BatchSpanProcessor,
)
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

os.environ['OPENAI_BASE_URL'] = 'https://ark.cn-beijing.volces.com/api/v3' # use ark model url by default, refer: https://www.volcengine.com/docs/82379/1361424
os.environ['OPENAI_API_KEY'] = '***'  # 设置一个大模型的api key

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://api.coze.cn/v1/loop/opentelemetry/v1/traces"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = "cozeloop-workspace-id=***,Authorization=Bearer ***"

otlp_exporter = OTLPSpanExporter(
    timeout=10,
)
trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(otlp_exporter)
)
tracer = trace.get_tracer(__name__)

# OpenInference自动检测
from openinference.instrumentation.crewai import CrewAIInstrumentor
from openinference.instrumentation.litellm import LiteLLMInstrumentor

CrewAIInstrumentor().instrument(skip_dep_check=True)
LiteLLMInstrumentor().instrument()

from crewai import Agent, Task, Crew, LLM

llm = LLM(
    model="openai/doubao-1-5-vision-pro-32k-250115",  # 配置模型名，如果是openai协议的模型，以openai/为前缀
)

# 定义Agent，带有roles and goals
coder = Agent(
    role='软件工程师',
    goal='根据指令，写出优雅清晰的代码',
    backstory='对软件技术有敏锐观察力的高级程序员',
    llm=llm,
)

# 为Agent创建任务
task1 = Task(
    description="定义HTML，用于制作带有标题的简单网站 - 你好! CozeLoop monitors your CrewAI agent!",
    expected_output="清晰简洁的HTML代码",
    agent=coder
)

# 创建Crew实例
crew = Crew(
    agents=[coder],
    tasks=[task1],
)

# 设置自定义Span节点 root_span
with tracer.start_as_current_span("root_span") as span:
    span.set_attribute("cozeloop.span_type", "custom")
    
    # 启动 crewAI kickoff
    result = crew.kickoff()
    print(result)
```

### 上报自定义节点 {#cda12c06}
如果你需要上报自定义 Span 节点，可以使用 OpenTelemetry SDK 手动创建 Span 并上报。OpenTelemetry SDK 手动上报的节点数据支持和自动上报的节点数据串联，形成完整的 Trace 调用树。
自定义的 OpenTelemetry Span，attribute 和 event 规范需遵循 [OpenTelemetry 字段映射](https://loop.coze.cn/open/docs/cozeloop/opentelemetry_field_mapping)。
```Python
# 设置自定义 Span 节点 root_span
with tracer.start_as_current_span("root_span") as span:
    span.set_attribute("cozeloop.span_type", "custom")
    
    # 启动 crewAI kickoff
    result = crew.kickoff()
    print(result)
```

## 查看 Trace {#5c7d2849}
上报 Trace 数据后，你可以在[扣子罗盘](https://loop.coze.cn/)的 **Trace** 页面，找到并单击目标 Span，查看上报的 Trace 数据。
![Image=719x433](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/f7dfa8ea834c4c6ab614a91371979697~tplv-goo7wpa0wc-image.image)
## 更多示例 {#bf7f782f}
关于上报 CrewAI Trace 数据的更多示例，请参考 [CrewAI](https://github.com/coze-dev/cozeloop-examples/tree/main/python/integration/framework/crewAI)。