跳到主要内容

Traceloop

Traceloop SDK 是一个面向 LLM 应用的轻量级埋点工具包。 它可以帮助开发者自动采集并导出追踪、指标以及其他关键可观测信号，用于分析基于 LLM 的工作流。

当它与 Instana 结合使用时，Traceloop 导出的遥测数据可以提供端到端可见性，让你能够查看追踪、分析性能瓶颈，并确保 LLM 驱动应用的稳定运行。

本指南演示如何通过 Traceloop SDK，把 Instana 可观测平台接入到你的 SkillFlaw 应用中，以便监控和分析 LLM 性能。

前置条件​

配置环境变量​

  1. 在 SkillFlaw 应用根目录中，编辑已有的 SkillFlaw .env 文件，或者创建一个新的。

  2. 填写以下环境变量，并根据你的部署环境替换占位值：


    _10
    TRACELOOP_API_KEY=tl_dummy_1234567890abcdef1234567890abcdef
    _10
    TRACELOOP_BASE_URL=https://otlp-magenta-saas.instana.rocks:4318
    _10
    TRACELOOP_HEADERS="x-instana-key=INSTANA_KEY"
    _10
    OTEL_EXPORTER_OTLP_INSECURE=false
    _10
    TRACELOOP_METRICS_ENDPOINT=HOST:8000
    _10
    TRACELOOP_METRICS_ENABLED=true
    _10
    OTEL_METRIC_EXPORT_INTERVAL=10000

    各变量含义如下：

    • TRACELOOP_API_KEY：用于让应用向 Traceloop 监控服务认证的 API Key。 可从 Traceloop 控制台获取。

      该集成依赖 Traceloop SDK 做埋点初始化，因此需要 Traceloop API Key。 如果你还没有这个 Key，也可以先使用前面示例中的占位值继续配置。

    • TRACELOOP_BASE_URL：Instana 的遥测采集端点地址，也就是你的 Instana backend endpoint，例如 https://otlp-magenta-saas.instana.rocks:4318。 可从 Instana 配置中获取，或向 Instana 管理员确认。

    • TRACELOOP_HEADERS：Instana 数据采集认证头。格式应为 "x-instana-key=INSTANA_KEY"，把 INSTANA_KEY 替换为你的 Instana key。

    • OTEL_EXPORTER_OTLP_INSECURE：OpenTelemetry Protocol 连接的安全设置。生产环境中的 Instana SaaS 一般设置为 false，表示使用 HTTPS / TLS；本地开发用不安全 HTTP 时，可设置为 true。

    • TRACELOOP_METRICS_ENDPOINT：指标采集端点地址，格式为 OTEL_DC_LLM_HOST:8000。请根据你的部署情况填写实际 collector 的可达主机与端口。

    • TRACELOOP_METRICS_ENABLED：是否启用指标采集。设置为 true 即可开启。

    • OTEL_METRIC_EXPORT_INTERVAL：指标导出间隔，单位毫秒。10000 表示每 10 秒导出一次，可根据监控需求调整。

  3. 确保 OpenTelemetry Data Collector（OTel DC）已经运行并正确配置。 打开 Collector 的 config.yaml，写入如下配置，并替换占位值：


    _10
    llm.application: "LLM_DC"
    _10
    instances:
    _10
    - otel.agentless.mode: true
    _10
    # Example endpoint: https://otlp-magenta-saas.instana.rocks:4318
    _10
    otel.backend.url: "INSTANA_ENDPOINT"
    _10
    otel.backend.using.http: false
    _10
    callback.interval: 10
    _10
    otel.service.name: "DC1"
    _10
    otel.service.port: 8000
    _10
    currency: "USD"

    该配置会让 OTel Collector 以 agentless 模式运行，并把遥测数据正确发送到你的 Instana backend，同时设置服务标识与采集间隔，便于后续监控。

使用 Traceloop 环境变量启动 SkillFlaw​

通过 .env 文件启动 SkillFlaw：


_10
uv run skillflaw run --env-file .env

Traceloop 会自动开始收集你的 LLM 应用遥测数据。

验证集成是否生效​

如果要确认可观测集成已正常工作，请按以下步骤检查：

  1. 在 SkillFlaw 中运行一个流程，产生真实流量。

  2. 在 Instana 中打开 Applications 查看追踪。

  3. 在 Services 中搜索你的 SkillFlaw 服务。

  4. 打开该服务，查看和分析关联调用。

    Instana Traces dashboard

  5. 如果要查看指标，请在 Instana 中打开 Infrastructure。

  6. 在 Analyze Infrastructure 中点击 Otel LLMonitor。

  7. 点击 LLM:DC1@your_machine_name.local 打开指标面板。

    Instana Metrics dashboard

另请参阅​