에이전트로 코드 계측하기

에이전트에게 프롬프트 하나를 전달하면, 서비스에 OpenTelemetry 자동 계측을 추가하고 sigiro를 가리킵니다. Claude Code, OpenCode, Codex에서 동작합니다.

이 가이드에서는 계측이 전혀 없는 서비스에 OpenTelemetry를 추가하는 방법을 설명하며, 편집 작업은 에이전트가 수행합니다. 아래 프롬프트를 에이전트에 붙여넣으십시오. 에이전트가 프레임워크를 감지하고, 공식 자동 계측을 설치한 뒤, 익스포터가 sigiro를 가리키도록 설정합니다.

이 방법은 Claude Code, OpenCode, Codex 또는 파일을 편집하고 패키지 관리자를 실행할 수 있는 모든 에이전트에서 동작합니다.

시작하기 전에

대상 서버로 사용할 sigiro 서버가 필요합니다. sigiro serve로 서버를 시작하거나, 퀵스타트의 Docker 명령으로 시작하십시오. 호스팅 서비스의 신규 사용자는 sigiro signup --name "Your Name" --email you@example.com을, 기존 계정은 sigiro auth login을 실행하십시오. 자체 호스팅 서버에는 인증 정보가 필요하지 않습니다.

자동 계측은 Python, Node.js, Java, .NET, Ruby용으로 제공됩니다. 서비스가 Go로 작성된 경우에는 이 프롬프트를 사용하지 마십시오. 대신 Go 섹션으로 이동하십시오.

1. 에이전트에 다음 프롬프트를 전달하십시오

엔드포인트를 교체하십시오. 호스팅 서비스를 사용하지 않는 경우 액세스 토큰 줄을 삭제하십시오.

Instrument this codebase for sigiro observability.

SIGIRO ENDPOINT: http://localhost:4318  (self-hosted; for hosted sigiro use
                 https://<your-sigiro-host> with no port)
HOSTED AUTH: sigiro signup --name "Your Name" --email you@example.com  (new account; use sigiro auth login for an existing account; omit for self-hosted)

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 ENDPOINT above exactly as given.
  A self-hosted server listens on :4318; a hosted one carries no port. Do not add
  or remove a port
- 호스팅 버전에서는 `sigiro auth token`으로 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)
- 호스팅 버전의 신규 사용자는 `sigiro signup --name "Your Name" --email you@example.com`, 기존 사용자는 `sigiro auth login`을 사용하고 인증 정보를 하드코딩하지 마십시오
- If a file already initializes the OTel SDK, update it rather than re-initializing
- 자동화에서만 환경 변수로 인증 정보를 읽고 대화형 사용에는 `sigiro signup` 또는 `sigiro auth login`을 사용하십시오

에이전트가 언어를 잘못 감지한 경우, 다음과 같이 직접 알려주십시오.

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

2. 에이전트에게 하지 말아야 할 일을 알려주십시오

에이전트는 여기서 필요 이상의 작업을 수행합니다. 에이전트가 시작하기 전에 다음 제한 사항을 명시하십시오.

OTel Collector를 설치하지 마십시오. sigiro가 컬렉터입니다.
각 엔드포인트마다 수동 스팬을 추가하지 마십시오. 자동 계측이 이를 처리합니다.
데이터베이스 연결 문자열이나 비즈니스 로직을 변경하지 마십시오.
대시보드나 알림 설정을 구성하지 마십시오. sigiro에는 둘 다 없습니다.

전체 작업은 다음과 같습니다. 프레임워크를 감지하고, 자동 계측을 설치하고, sigiro를 가리키도록 설정하는 것입니다.

3. 확보되는 커버리지를 확인하십시오

언어	접근 방식	커버리지
Python	`opentelemetry-instrument` CLI + distro	HTTP(FastAPI, Flask, Starlette), DB(psycopg2, asyncpg), Redis
Node.js	`@opentelemetry/auto-instrumentations-node`	HTTP(Express, Fastify), DB(pg, mysql2, mongoose)
Java	`opentelemetry-javaagent.jar`	HTTP(서블릿, Spring), DB(JDBC), JVM 메트릭
.NET	`OpenTelemetry.AutoInstrumentation` 시작 훅	HTTP(ASP.NET Core), DB(EF Core)
Ruby	`opentelemetry-instrumentation-all` gem	HTTP(Rails), DB(ActiveRecord), Sidekiq
Go	`otelc` 컴파일 타임 계측	HTTP 서버 스팬, Go 런타임 메트릭, 서드파티 라이브러리

특정 라이브러리에서 스팬이 생성되지 않는 경우, 해당 라이브러리에 한해서만 수동으로 스팬을 추가하십시오.

자동 계측의 커버리지는 위 표에서 시사하는 것보다 좁으므로, 다음 두 가지 공백은 미리 예상해 두는 것이 좋습니다.

로그. 기본 제공되는 로그 브리지는 이름이 지정된 로거를 대상으로 합니다. Node에서는 pino, winston, bunyan이며, Python에서는 표준 logging 모듈입니다. console.log나 print로 기록하는 서비스는 트레이스와 메트릭은 생성하지만 로그는 생성하지 않습니다. 직접 브리지를 작성하기보다 제대로 된 로거로 전환하십시오.

공식 계측이 인식하지 못하는 데이터베이스. 위 표의 각 DB 항목은 특정 드라이버를 명시합니다. instrumentation-pg는 node-postgres를 패치하므로, postgres.js를 사용하는 Node 서비스에서는 쿼리 스팬이 생성되지 않으며, ORM도 이 공백을 메우지 못합니다. drizzle-orm은 drizzle-orm/tracing에 트레이서를 포함하지만, 배포된 패키지에서 해당 트레이서의 await import('@opentelemetry/api')가 주석 처리되어 있어 스팬을 생성할 수 없습니다. DB 열의 내용을 신뢰하기 전에 사용 중인 드라이버가 목록에 있는지 확인하고, 수동으로 스팬을 작성하기보다 해당 ORM에 대해 유지 관리되는 래퍼를 사용하십시오.

Go: 소스가 아니라 빌드를 계측하십시오

Go에 대해서는 이 작업을 에이전트에게 맡기지 마십시오. Go에서는 빌드 명령에 접두사를 추가하면 계측된 바이너리가 생성됩니다. 소스 파일은 전혀 변경하지 않습니다. 사용하는 도구는 otelc이며, OpenTelemetry 프로젝트에서 빌드합니다. 이 도구는 사용자가 제어할 수 없는 서드파티 라이브러리까지 계측하는데, 에이전트는 자신의 코드만 편집하므로 이를 수행할 수 없습니다.

v1.0.1 릴리스에서 사용 중인 플랫폼용 바이너리를 다운로드하십시오. 이 릴리스는 arm64 및 x86-64 기반 macOS와 Linux, 그리고 x86-64 기반 Windows용 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

이 바이너리는 시작 시 트레이스 프로바이더, 미터 프로바이더, 로거 프로바이더를 생성합니다. 사용자가 작성한 SDK 코드는 필요하지 않습니다. 서비스는 HTTP 서버 스팬과 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입니다. 호스팅 서비스에서는 그 반대로, 엔드포인트에 포트가 없는지 확인하고, localhost가 아니라 https://<your-sigiro-host>/v1/services를 액세스 토큰과 함께 조회하십시오. sigiro status를 실행하여 서버가 정상 상태인지 확인하십시오. 잘못된 익스포터 설정은 부팅 시점에 오류를 보고하므로, 서비스 자체의 로그에서 OTel 시작 오류를 확인하십시오.

호스팅 서비스에서는 헤더가 정확히 Authorization: Bearer <oauth-access-token> 형식인지 확인하십시오. 자체 호스팅 서버는 모든 인증 헤더를 무시합니다. 따라서 토큰이 잘못되어도 메시지나 401 응답 없이 실패합니다.

다음 단계

퀵스타트 — 무엇이 어떻게 왜 변경되었는지 질의하기
에이전트 자체의 텔레메트리를 sigiro로 전송하기 — Claude Code나 Codex도 sigiro를 가리키도록 설정하기
호스팅 sigiro로 텔레메트리 전송하기 — 서버를 직접 운영하고 싶지 않은 경우 사용