자체 운영 PostgreSQL

pg_tracing 확장을 사용하여 PostgreSQL이 직접 스팬을 전송하도록 구성합니다. 이미지 빌드, 서버 설정, 검증 절차와 앱 키 제약을 설명합니다.

동작 방식

pg_tracing은 애플리케이션이 쿼리에 SQLCommenter 주석으로 전달한 W3C traceparent를 해석합니다. 해당 트레이스의 하위 스팬으로 서버 측 스팬을 생성하며, 전송은 백그라운드 워커가 OTLP로 직접 수행합니다. SDK를 경유하지 않습니다.

스팬은 두 계층으로 생성됩니다. track이 생성하는 문장 단위 스팬과 planstate_spans가 생성하는 실행계획 노드 단위 스팬입니다. 후자를 비활성화하면 SeqScan, Hash Join과 같은 노드는 수집되지 않고 문장 전체의 소요 시간만 기록됩니다.

요구 사항

이미지 빌드

확장은 배포판 패키지로 제공되지 않으므로 직접 빌드해야 합니다. Sophonz는 다음 Dockerfile로 빌드한 이미지를 사용합니다.

FROM postgres:16-bookworm AS build
ARG PG_TRACING_REF=v0.1.3
 
RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        build-essential git ca-certificates postgresql-server-dev-16 \
        libcurl4-openssl-dev; \
    git clone --depth 1 --branch "${PG_TRACING_REF}" \
        https://github.com/DataDog/pg_tracing.git /tmp/pg_tracing; \
    make -C /tmp/pg_tracing install; \
    rm -rf /var/lib/apt/lists/* /tmp/pg_tracing
 
FROM postgres:16-bookworm
RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends libcurl4 ca-certificates; \
    rm -rf /var/lib/apt/lists/*
 
COPY --from=build /usr/lib/postgresql/16/lib/pg_tracing.so /usr/lib/postgresql/16/lib/
COPY --from=build /usr/share/postgresql/16/extension/pg_tracing* /usr/share/postgresql/16/extension/

Debian 기반 이미지를 사용하는 이유는 pgxs 툴체인이 지원되는 환경이기 때문입니다. Alpine에서는 헤더와 툴체인을 별도로 구성해야 합니다.

서버 설정

shared_preload_libraries는 서버 시작 시점에 로드되어야 하므로 서버 인자로 전달합니다.

- -c
- shared_preload_libraries=pg_tracing
- -c
- compute_query_id=on
- -c
- pg_tracing.track=all
- -c
- pg_tracing.planstate_spans=on
- -c
- pg_tracing.otel_naptime=2000
- -c
- pg_tracing.otel_service_name=my-postgres
- -c
- pg_tracing.otel_endpoint=https://in.sophonz.ai/v1/traces

설치 후 데이터베이스에서 확장을 활성화합니다.

CREATE EXTENSION IF NOT EXISTS pg_tracing;

샘플링

기본값은 sample_rate = 0, caller_sample_rate = 1입니다. PostgreSQL은 샘플링된 traceparent와 함께 전달된 쿼리만 추적하며, 그 외의 쿼리는 추적하지 않습니다. 데이터베이스가 독자적으로 샘플링을 결정하지 않으므로, 애플리케이션 트레이스에 포착된 요청은 데이터베이스 스팬을 함께 포함합니다.

sample_rate를 상향하면 애플리케이션과 무관하게 데이터베이스가 자체적으로 추적을 시작합니다. 이때 생성되는 스팬은 상위 스팬이 없으므로 별도의 트레이스로 기록됩니다.

애플리케이션 설정

PostgreSQL이 traceparent를 해석하려면 애플리케이션이 쿼리에 이를 포함하여 전달해야 합니다. 이 역할을 하는 것이 SQLCommenter입니다. 특정 언어의 기능이 아니라 여러 OpenTelemetry 구현이 공유하는 규약이지만, 기본값으로 켜져 있지 않으므로 명시적으로 활성화해야 합니다.

Node.js SDK에서는 instrumentations 옵션으로 하위 계측에 전달합니다.

init({
  service: 'my-api',
  apiKey: process.env.SOPHONZ_API_KEY,
  instrumentations: {
    '@opentelemetry/instrumentation-pg': {
      addSqlCommenterCommentToQueries: true,
    },
  },
});

이 설정이 없으면 쿼리에 주석이 붙지 않고, PostgreSQL은 추적할 근거를 받지 못합니다. 확장은 정상 동작하지만 스팬은 생성되지 않습니다.

앱 키 제약

해결 방법은 배포 형태에 따라 다릅니다.

• Sophonz 관리형 — 이미 적용되어 있습니다. 수집기에 내부 전용 수신 포트를 두고, 수신 시점에 키를 부여합니다.
• 온프레미스·자체 호스팅 — 도입 시 함께 구성합니다. 엔터프라이즈 개요를 참고하거나 문의해 주세요.

검증

확장이 스팬을 생성하여 전송하고 있는지 먼저 확인합니다.

SELECT * FROM pg_tracing_info();

처리된 스팬 수와 마지막 전송 시각을 반환합니다. 이 값이 증가하는데도 트레이스가 비어 있다면, 유실은 데이터베이스가 아니라 수집 경로에서 발생한 것입니다.

실제로 적용된 설정은 pg_settings에서 확인합니다. 오타가 포함된 GUC는 경고 없이 무시되므로, 서버 인자만으로 적용 여부를 판단해서는 안 됩니다.

SELECT name, setting FROM pg_settings
WHERE name LIKE 'pg_tracing%' ORDER BY name;

마지막으로 단일 트레이스에 포함된 서비스를 확인합니다.

SELECT serviceName, count()
FROM sophonz_traces.distributed_sophonz_index_v2
WHERE traceID = '...'
GROUP BY 1;

애플리케이션과 데이터베이스가 모두 조회되어야 합니다. 데이터베이스만 누락된 경우에는 컨텍스트 전파가 아니라 수집 단계의 문제입니다. 전파 여부는 별도로 확인할 수 있습니다. 애플리케이션 응답의 Server-Timing 헤더에 요청 시 전송한 것과 동일한 트레이스 ID가 포함되어 있으면 전파는 정상입니다.