Go

공식 go.opentelemetry.io 모듈을 사용해 별도의 Sophonz 패키지 없이 모든 Go 서버에서 트레이스, 메트릭, 로그를 Sophonz로 전송하세요.

@sophonz/go-sdk는 존재하지 않으며, 필요하지도 않습니다. Sophonz 컬렉터는 표준 OTLP를 사용하므로, 모든 Go 서비스는 공식 go.opentelemetry.io/otel 모듈을 연결하고 환경 변수로 Sophonz를 가리키기만 하면 트레이스, 메트릭, 로그를 전송할 수 있습니다.

제공되는 것

  • 공식 Go SDK — go.opentelemetry.io/otel과 트레이스·로그용 OTLP-over-HTTP 익스포터. 둘 다 별도 설정 코드 없이 표준 OTEL_EXPORTER_OTLP_* 환경 변수를 그대로 읽습니다.
  • 주요 라우터와 HTTP 클라이언트를 위한 미들웨어 계측 — net/http용 otelhttp와, 인기 프레임워크용 otelgin, otelecho 등이 스팬을 대신 생성해 줍니다.
  • 한 번만 작성하면 되는 작고 명시적인 설정 함수 — Go에는 Java처럼 바이트코드를 재작성하는 에이전트가 없으므로, SDK 연결은 플래그 하나가 아니라 몇 줄의 코드로 이뤄지지만 이후로는 바꿀 일이 없습니다.

동작 방식

Go에는 런타임에 패치할 바이트코드가 없기 때문에 Java 같은 코드 변경 없는(zero-code) 자동 계측 에이전트가 존재하지 않습니다. 대신 시작 시점에 짧은 설정 함수를 한 번 호출합니다.

  1. 서비스를 설명하는 Resource를 만듭니다 (resource.WithFromEnv()를 통해 OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES를 읽음).
  2. OTLP HTTP 트레이스 익스포터(otlptracehttp.New)와 로그 익스포터(otlploghttp.New)를 생성합니다 — 둘 다 엔드포인트, 프로토콜, 헤더를 OTEL_EXPORTER_OTLP_* 환경 변수에서 바로 가져옵니다.
  3. 결과로 만들어진 TracerProvider / LoggerProvider를 전역 프로바이더로 등록합니다.

이후 라우터나 http.Handler를 otelhttp.NewHandler(또는 프레임워크별 미들웨어)로 감싸면 모든 요청에 자동으로 스팬이 생성됩니다.

CAUTION — 유효한 service.key가 없으면 텔레메트리는 조용히 버려집니다

Sophonz 컬렉터는 강제 모드(enforce mode)로 동작합니다. 즉, OTLP 페이로드는 네트워크상으로 정상 수신되더라도 해석 가능한 service.key 리소스 속성이 없으면 조용히 폐기됩니다. 애플리케이션에 오류가 발생하지도, 요청이 거부되지도 않습니다 — 그저 콘솔이 비어 있을 뿐입니다. 다른 문제라고 넘겨짚기 전에 OTEL_RESOURCE_ATTRIBUTES(그리고 OTEL_EXPORTER_OTLP_HEADERS)부터 다시 확인하세요.

TIP — 다음 단계

정확한 go get 명령, 설정 코드, 환경 변수 표, 프레임워크별 참고 사항은 설치 문서를 확인하세요.