使用智能体为代码添加检测

只需给智能体一条提示词。智能体会为你的服务添加 OpenTelemetry 自动检测，并将其指向 sigiro。此方法适用于 Claude Code、OpenCode 和 Codex。

本指南介绍如何为一个尚未接入任何检测的服务添加 OpenTelemetry，具体的代码修改由智能体完成。把下面的提示词粘贴给智能体即可。智能体会检测你的框架、安装官方自动检测组件，并把导出器指向 sigiro。

此方法适用于 Claude Code、OpenCode、Codex，或任何能够编辑文件并运行你的包管理器的智能体。

开始之前

你需要一个 sigiro 服务端作为数据目的地。可以用 sigiro serve 启动，也可以使用快速开始中的 Docker 命令启动。自托管服务端不需要密钥。只有托管服务需要密钥，密钥的格式为 sk_<tenant>_<random>。

Python、Node.js、Java、.NET 和 Ruby 均有自动检测方案。如果你的服务是 Go，请不要使用该提示词，改为查看 Go 章节。

1. 把这条提示词交给智能体

替换其中的 endpoint。除非使用托管服务，否则删除密钥那一行。

Instrument this codebase for sigiro observability.

SIGIRO ENDPOINT: http://localhost:4318  (replace with your OTLP ingest address)
HOSTED API KEY: sk_<tenant>_<random>  (omit entirely for a self-hosted server)

Goal: add OpenTelemetry auto-instrumentation so this service emits traces,
metrics, and logs to sigiro. Make the minimum change that works — prefer
auto-instrumentation over hand-written spans.

Rules:
- Detect the language and framework automatically
- Use official OTel auto-instrumentation where it exists (Python opentelemetry-instrument,
  Java javaagent, Node.js auto-instrumentations-node, etc.)
- If auto-instrumentation is not available for this language/framework, add
  manual OTel SDK spans for HTTP handlers and database calls
- Set OTEL_EXPORTER_OTLP_ENDPOINT to the sigiro OTLP HTTP endpoint (:4318)
- For hosted sigiro only, set OTEL_EXPORTER_OTLP_HEADERS with the tenant bearer token
- Set OTEL_SERVICE_NAME to identify this service (use the existing service name or repo name)
- Use the existing package manager (pip, npm, Maven, Gradle, gem, go get)
- For hosted sigiro, do NOT hardcode the tenant key — read it from SIGIRO_API_KEY
- If a file already initializes the OTel SDK, update it rather than re-initializing
- Add SIGIRO_API_KEY to .env.example only for a hosted deployment

如果智能体识别错了语言，直接告诉它：

Language: <python|nodejs|java|dotnet|ruby>
Framework: <fastapi|express|spring-boot|rails|...>

2. 告诉智能体不要做什么

在这个场景下，智能体做的事情往往超出你的需要。开始之前先明确这些边界：

不要安装 OTel Collector。sigiro 本身就是 collector。
不要为每个接口手写 span。自动检测已经覆盖它们。
不要修改数据库连接串或业务逻辑。
不要配置仪表盘或告警。sigiro 两者都没有。

完整的任务就是：检测框架、安装自动检测、把它指向 sigiro。

3. 检查你获得的覆盖范围

语言	方案	覆盖范围
Python	`opentelemetry-instrument` CLI + distro	HTTP（FastAPI、Flask、Starlette）、数据库（psycopg2、asyncpg）、Redis
Node.js	`@opentelemetry/auto-instrumentations-node`	HTTP（Express、Fastify）、数据库（pg、mysql2、mongoose）
Java	`opentelemetry-javaagent.jar`	HTTP（Servlets、Spring）、数据库（JDBC）、JVM 指标
.NET	`OpenTelemetry.AutoInstrumentation` startup hook	HTTP（ASP.NET Core）、数据库（EF Core）
Ruby	`opentelemetry-instrumentation-all` gem	HTTP（Rails）、数据库（ActiveRecord）、Sidekiq
Go	`otelc` 编译期检测	HTTP 服务端 span、Go 运行时指标、第三方库

如果某个库没有产生 span，只针对该库手写 span 即可。

Go：检测构建过程，而不是源码

不要把这项工作交给智能体处理 Go 项目。对于 Go，你只需在构建命令前加一个前缀，产出的二进制文件就自带检测。你不需要改动任何源文件。相应的工具叫 otelc，由 OpenTelemetry 项目构建。该工具还会检测你无法控制的第三方库，而智能体做不到这一点，因为智能体只能编辑你自己的代码。

从 v1.0.1 release 下载适用于你平台的二进制文件。该 release 提供了 macOS 与 Linux 的 arm64 和 x86-64 版本，以及 Windows 的 x86-64 版本的 otelc：

curl -fsSL -o otelc https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/releases/download/v1.0.1/otelc-darwin-arm64
chmod +x otelc
./otelc version

go install 对这个工具不起作用。该模块没有发布命令路径。如果你的平台没有对应的构建产物，请克隆仓库并运行 make build。

然后在你平时的构建命令前加上 otelc：

./otelc go build -o checkout .

首次构建会下载 OpenTelemetry 相关包，因此比普通构建耗时更长。你的 go.mod 文件保持不变。

启动二进制文件时使用与快速开始相同的两个环境变量：

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_SERVICE_NAME=checkout \
  ./checkout

二进制文件会在启动时创建 trace provider、meter provider 和 logger provider。它不需要你编写任何 SDK 代码。该服务会上报 HTTP 服务端 span 和 Go 运行时指标。

有两点限制。该工具需要 Go 1.25 或更高版本；当前版本为 1.0.1，由项目于 2026 年 7 月 14 日打标签发布。关于它所覆盖的库，请阅读上游文档。

4. 确认检测生效

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_SERVICE_NAME=my-service \
  <your-app-start-command>

然后询问 sigiro 收到了哪些服务：

curl http://localhost:9999/v1/services

在有真实流量后的几秒钟内，你的服务就会出现。它出现之后，sigiro diagnose my-service 就有数据可读了。

如果服务没有出现，请做以下检查。确认端口：HTTP 用 :4318，gRPC 用 :4317。运行 sigiro status 确认服务端健康。查看你自己服务的日志，看是否有 OTel 启动错误，因为导出器配置错误会在启动时报告故障。

在托管服务上，确认请求头严格为 Authorization: Bearer sk_<tenant>_<random>。自托管服务端会忽略所有认证头。因此错误的密钥在自托管环境下不会有任何提示，也不会返回 401。

下一步

快速开始 —— 询问发生了什么变化以及原因
把智能体自身的遥测数据发送到 sigiro —— 把 Claude Code 或 Codex 也指向 sigiro
向托管版 sigiro 发送遥测数据 —— 如果你不想自己运行服务端，请使用这种方式