SigNoz 관측성

SigNoz 관측성

SigNoz 는 모니터링과 관측성 요구를 모두 충족하는 단일 도구예요. SigNoz를 선택해야 하는 몇 가지 이유는 다음과 같아요:

  • 관측성(로그, 메트릭, 트레이스)을 위한 단일 도구
  • 오픈소스 표준인 OpenTelemetry 기반이라 어떤 종류의 벤더 락인이든 자유로워요
  • 상관된 로그·메트릭·트레이스로 디버깅 시 훨씬 풍부한 컨텍스트 제공
  • 관측성 데이터용으로 극도로 빠르고 고도로 최적화된 저장소인 ClickHouse(Uber·Cloudflare 같은 곳도 사용)를 데이터스토어로 사용
  • 관측성 데이터 쿼리에 대한 모든 사용 사례를 충족하는 DIY 쿼리 빌더, PromQL, ClickHouse 쿼리

출처: 문서

본문

설정 (Setup)

Next.js 애플리케이션 계측 (Instrument your Next.js application)

Next.js 애플리케이션에서 OpenTelemetry 계측을 설정하고 SigNoz에서 애플리케이션 트레이스를 보는 방법에 대한 자세한 지침은 여기에서 확인하세요.

SigNoz Cloud로 트레이스 직접 보내기 (Send traces directly to SigNoz Cloud)

1단계. OpenTelemetry 패키지 설치

npm install @vercel/otel @opentelemetry/api @ai-sdk/otel

2단계. instrumentationHook을 포함하도록 next.config.mjs 업데이트

이 단계는 NextJs 14 이하를 사용할 때만 필요해요.

/** @type {import('next').NextConfig} */
const nextConfig = {
  // instrumentationHook 실험적 기능 포함
  experimental: {
    instrumentationHook: true,
  },
};
export default nextConfig;

3단계. instrumentation.ts 파일 생성 (프로젝트 루트 디렉토리)

import { registerTelemetry } from 'ai';
import { LegacyOpenTelemetry } from '@ai-sdk/otel';
import { registerOTel, OTLPHttpJsonTraceExporter } from '@vercel/otel';
// otel 로깅 추가
import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // 디버깅 시 diag log level을 DEBUG로 설정

registerTelemetry(new LegacyOpenTelemetry());

export function register() {
  registerOTel({
    serviceName: '<service_name>',
    traceExporter: new OTLPHttpJsonTraceExporter({
      url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
      headers: { 'signoz-ingestion-key': '<your-ingestion-key>' },
    }),
  });
}
  • <service_name> 은 서비스 이름이에요
  • SigNoz Cloud region에 맞게 <region> 을 설정하세요
  • <your-ingestion-key> 를 SigNoz 수집 키로 교체하세요

계측 파일은 프로젝트 루트에 있어야 하며 app이나 pages 디렉토리 안이 아니에요. src 폴더를 사용한다면 pages와 app 옆의 src 안에 파일을 두세요.

이제 Next.js 앱이 제대로 계측되었을 거예요.

Vercel AI SDK용 텔레메트리 활성화 (Enable Telemetry for Vercel AI SDK)

Vercel AI SDK는 OpenTelemetry를 사용해 텔레메트리 데이터를 수집해요. OpenTelemetry는 텔레메트리 데이터 수집을 위한 표준화된 계측을 제공하도록 설계된 오픈소스 관측성 프레임워크예요.

텔레메트리 활성화 (Enabling Telemetry)

Vercel AI SDK의 텔레메트리 옵션에 대한 더 자세한 정보는 여기를 참고하세요.

@ai-sdk/otel 설치와 instrumentation.ts에 registerTelemetry 추가(위 3단계 참고)만으로 모든 AI SDK 호출에서 텔레메트리가 자동으로 캡처돼요:

const result = await generateText({
  model: openai('gpt-6-luna'),
  prompt: 'Write a short story about a cat.',
});

함수의 입력 값과 출력 값을 기록할지 여부도 제어할 수 있어요. 기본적으로 둘 다 활성화돼요. recordInputs와 recordOutputs 옵션을 false로 설정해 비활성화할 수 있어요.

telemetry: { recordInputs: false, recordOutputs: false }

입력·출력 기록을 비활성화하는 것은 프라이버시, 데이터 전송, 성능 면에서 유용할 수 있어요. 예를 들어 입력에 민감한 정보가 들어 있다면 입력 기록을 비활성화하고 싶을 거예요.

텔레메트리 메타데이터 (Telemetry Metadata)

functionId를 제공해 텔레메트리 데이터가 어떤 함수를 위한 것인지 식별하고, context로 텔레메트리 데이터에 추가 정보를 포함할 수 있어요.

const result = await generateText({
  model: openai('gpt-6-luna'),
  prompt: 'Write a short story about a cat.',
  context: {
    something: 'custom',
    someOtherThing: 'other-value',
  },
  telemetry: {
    functionId: 'my-awesome-function',
  },
});

커스텀 트레이서 (Custom Tracer)

트레이스가 @opentelemetry/api 싱글톤이 제공하는 TracerProvider가 아닌 것을 사용하길 원한다면, LegacyOpenTelemetry 생성자에 커스텀 Tracer를 전달하세요:

import { registerTelemetry, generateText } from 'ai';
import { LegacyOpenTelemetry } from '@ai-sdk/otel';

const tracerProvider = new NodeTracerProvider();
registerTelemetry(
  new LegacyOpenTelemetry({
    tracer: tracerProvider.getTracer('ai'),
  }),
);

const result = await generateText({
  model: openai('gpt-6-luna'),
  prompt: 'Write a short story about a cat.',
});

이제 Vercel AI SDK 명령이 자동으로 트레이스, 스팬, 이벤트를 발행할 거예요. 생성되는 스팬과 이벤트 유형에 대한 자세한 내용은 여기에서 확인할 수 있어요.

마지막으로 이 데이터를 SigNoz Cloud의 트레이스 탭에서 볼 수 있을 거예요.

더 알아보기 (Learn more)

전체 사이트맵