콘텐츠로 이동

DataKit Operator로 Beacon 주입

Beacon은 DataKit Operator의 권장 에이전트입니다. 배포 템플릿의 Java 규칙은 이미지 ghcr.io/beacon-observability/beacon-java:1.3.4@sha256:6d6316a2aae05cd926335bb3819a813ed0cae7d12faaf6497c2adf040a67b888를 사용하며, default 네임스페이스에서 admission.datakit/beacon-language=java 레이블이 있는 Pod에만 일치합니다. Node.js, Python, OpenTelemetry, DDTrace에는 각각 별도 규칙을 추가하세요.

빠른 시작

  1. DataKit Operator를 설치하고 DataKit OpenTelemetry 수집기를 활성화합니다. 애플리케이션 Pod에서 DataKit Service로 연결할 수 있는지 확인하세요.
  2. 언어에 해당하는 Pod 레이블과 서비스 이름에 사용할 app 레이블을 설정하세요. 기본 Java 규칙을 사용하거나 해당 워크로드의 규칙을 추가하세요.
  3. ConfigMap을 직접 수정했다면 Operator를 재시작합니다. 애플리케이션 Pod를 다시 만들고 에이전트가 지원하는 요청을 보낸 후 OTEL_SERVICE_NAME으로 트레이스를 조회하세요.

Java 런타임의 호환성은 사용할 Beacon 릴리스에서 확인하세요. 규칙은 Pod의 모든 일반 컨테이너에 적용됩니다. 언어별로 대상 워크로드를 선택하세요.

기본 Java 이미지는 digest를 고정하고 IfNotPresent를 사용합니다. 노드에서 ghcr.io에 접근할 수 없다면 같은 이미지를 노드에 미리 로드하거나, 접근 가능한 레지스트리에 미러링한 뒤 규칙의 image를 업데이트하세요.

규칙 구성

다음 규칙은 모든 네임스페이스에서 Java 레이블이 있는 Pod에 Beacon을 주입합니다. admission_inject_v2.beacons에 추가하세요.

{
    "admission_inject_v2": {
        "beacons": [
            {
                "name": "beacon-java",
                "language": "java",
                "namespace_selectors": [
                    "*"
                ],
                "label_selectors": [
                    "admission.datakit/beacon-language=java"
                ],
                "check_annotation": false,
                "image": "ghcr.io/beacon-observability/beacon-java:1.3.4@sha256:6d6316a2aae05cd926335bb3819a813ed0cae7d12faaf6497c2adf040a67b888",
                "image_pull_policy": "IfNotPresent",
                "envs": {
                    "POD_NAME": "{fieldRef:metadata.name}",
                    "POD_NAMESPACE": "{fieldRef:metadata.namespace}",
                    "OTEL_SERVICE_NAME": "{fieldRef:metadata.labels['app']}",
                    "OTEL_RESOURCE_ATTRIBUTES": "k8s.pod.name=$(POD_NAME),k8s.namespace.name=$(POD_NAMESPACE)",
                    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
                    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://datakit-service.datakit.svc.cluster.local:9529/otel",
                    "OTEL_TRACES_EXPORTER": "otlp",
                    "OTEL_METRICS_EXPORTER": "none",
                    "OTEL_LOGS_EXPORTER": "none",
                    "OTEL_PROFILING_ENABLED": "false",
                    "BEACON_SECURITY_ENABLED": "false"
                }
            }
        ]
    }
}

HTTP/Protobuf 기본 주소에는 /otel이 필요합니다. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 같은 신호별 변수에는 http://datakit-service.datakit.svc.cluster.local:9529/otel/v1/traces와 같이 전체 경로를 지정해야 합니다. 신호별 변수는 기본 주소보다 우선합니다.

Java 애플리케이션 배포

이미지를 Java 애플리케이션 이미지로 교체하세요. 이 Deployment는 배포 기본 Java 규칙과 위 레이블 규칙에 모두 일치합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: beacon-java-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: beacon-java-demo
  template:
    metadata:
      labels:
        app: beacon-java-demo
        admission.datakit/beacon-language: java
      annotations:
        admission.datakit/beacon.enabled: "true"
        admission.datakit/otel.enabled: "false"
        admission.datakit/ddtrace.enabled: "false"
    spec:
      containers:
        - name: app
          image: registry.example.com/apps/java-demo:1.0.0

Node.js 트레이싱

Linux amd64 또는 arm64의 Debian Bookworm(glibc)에서 Node.js 24를 사용하세요. Operator는 다음 사전 로드 옵션을 NODE_OPTIONS에 추가합니다.

--import=/beacon-auto-instrumentation-nodejs/node_modules/@beacon-observability/nodejs/register.mjs

admission_inject_v2.beacons에 규칙을 추가하고 Pod 템플릿에 admission.datakit/beacon-language: nodejs를 설정하세요.

{
  "name": "beacon-nodejs",
  "language": "nodejs",
  "namespace_selectors": [
    "*"
  ],
  "label_selectors": [
    "admission.datakit/beacon-language=nodejs"
  ],
  "image": "ghcr.io/beacon-observability/beacon-nodejs:2.0.2@sha256:f9aeac2c291361db7696f6dd154f26b9dd6c2231bc6bbdc4ed20ef484c241f3e",
  "image_pull_policy": "IfNotPresent",
  "envs": {
    "OTEL_SERVICE_NAME": "{fieldRef:metadata.labels['app']}",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://datakit-service.datakit.svc.cluster.local:9529/otel",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf"
  }
}

Beacon Node.js 가이드

Python 트레이싱

Linux amd64 또는 arm64의 Debian Bookworm(glibc)에서 표준 GIL CPython 3.13을 사용하세요. Operator는 PYTHONPATH로 sitecustomize.py를 로드합니다. 이미지에는 requests 계측이 포함됩니다.

admission_inject_v2.beacons에 규칙을 추가하고 Pod 템플릿에 admission.datakit/beacon-language: python을 설정하세요. 인터프리터의 site 및 환경 변수 처리를 활성화하세요. 번들 패키지는 애플리케이션의 기본 site-packages보다 먼저 검색됩니다. 사용자 정의 sitecustomize나 종속성 충돌이 있는 Pod에서는 tracing 주입을 비활성화하세요.

{
  "name": "beacon-python",
  "language": "python",
  "namespace_selectors": [
    "*"
  ],
  "label_selectors": [
    "admission.datakit/beacon-language=python"
  ],
  "image": "ghcr.io/beacon-observability/beacon-python:1.2.4@sha256:330cdcc062381af47668337fbdc56bec5a6211e77cea85fed6d91a1ebe280808",
  "image_pull_policy": "IfNotPresent",
  "envs": {
    "OTEL_SERVICE_NAME": "{fieldRef:metadata.labels['app']}",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://datakit-service.datakit.svc.cluster.local:9529/otel",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf"
  }
}

Beacon Python 가이드

주입 및 에이전트 선택

우선순위, 상호 배타 및 스위치는 주입 규칙을 참조하세요.

Pod에 tracing용 init Container, 전용 볼륨 또는 마운트가 있으면 Operator는 기존 에이전트를 유지하고 webhook이 다시 호출되어도 Beacon 주입을 건너뜁니다. 에이전트 구성 변경을 적용하려면 Pod를 다시 생성하세요.

규칙의 환경 변수는 구성 순서대로 추가하며, 애플리케이션에 명시한 동명의 env 항목이 우선합니다. 기본값은 트레이스를 OTLP로 내보내고 Metric, Log, Profile, Security를 비활성화합니다.

JAVA_TOOL_OPTIONS, NODE_OPTIONS, PYTHONPATH 중 해당 변수를 envFrom에서 가져올 수 있고 명시적으로 선언하지 않았다면 Beacon은 해당 Pod의 주입을 건너뜁니다. 주입하려면 컨테이너의 env에서 해당 시작 변수를 선언하고 기존 값을 유지하세요.

Java 시작 옵션

Operator는 datakit-beacon-lib-init을 추가하여 이미지의 /javaagent.jar를 EmptyDir datakit-beacon-auto-instrument에 복사합니다. 애플리케이션 컨테이너에는 /beacon-auto-instrumentation-java를 읽기 전용으로 마운트하고 JAVA_TOOL_OPTIONS에 -javaagent:/beacon-auto-instrumentation-java/javaagent.jar를 추가합니다.

Java에서는 모든 애플리케이션 컨테이너의 command, args, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, _JAVA_OPTIONS를 확인합니다. 시작 인수의 $(VAR)를 선언 순서에 따라 해석하고 원래 구성을 유지합니다. 컨테이너 하나라도 이미 APM 에이전트를 로드하거나 식별할 수 없는 -javaagent를 사용하면 Pod 전체의 tracing 주입을 건너뜁니다. JVM 옵션 변수가 중복되거나, 값이 valueFrom에서 오거나, 참조를 해석할 수 없는 경우도 마찬가지입니다. 식별된 JaCoCo는 APM 에이전트와 함께 사용할 수 있습니다.

Operator는 Pod에 명시된 시작 옵션을 확인합니다. 애플리케이션이 JVM @file 또는 envFrom의 설정을 통해 이미 에이전트를 로드한다면 admission.datakit/tracing.enabled: "false"를 설정하세요.

스위치, 버전 및 권한

admission.datakit/beacon.enabled: "false"는 Beacon을 비활성화합니다. check_annotation: true이면 Pod에 admission.datakit/beacon-<language>-lib.version을 설정해야 합니다. <language>에는 java, nodejs, python 중 하나를 사용합니다. 이 값은 이미지 tag를 대체하고 기존 digest를 제거합니다. tag 예시는 1.3.4입니다. digest를 고정할 때는 check_annotation: false를 유지하세요.

추가되는 init Container의 기본 UID/GID는 65532이며 runAsNonRoot, 읽기 전용 루트 파일시스템, 권한 상승 금지, 모든 capabilities 제거를 설정합니다. Pod에 0이 아닌 UID가 명시되어 있으면 해당 UID를 사용하고 GID가 명시되어 있으면 해당 GID를 사용합니다. 기존 Pod seccomp 설정을 상속하고 없으면 RuntimeDefault를 사용합니다. 애플리케이션 컨테이너 권한이나 Pod의 fsGroup은 변경하지 않습니다. 사용자 정의 에이전트 이미지는 해당 언어의 디렉터리 구조를 유지하고 init 컨테이너가 에이전트 파일을 읽고 EmptyDir에 쓸 수 있도록 해야 합니다.

읽기 전용 루트 파일 시스템

Beacon Java 1.3.4는 시작할 때 임시 디렉터리에 내장 확장 기능의 압축을 풉니다. 애플리케이션 컨테이너에 readOnlyRootFilesystem: true를 설정하고 /tmp에 쓸 수 없으면 JVM 로그에 Failed to open embedded extensions가 표시됩니다. 이때도 기본 트레이스는 전송될 수 있습니다. 기존의 쓰기 가능한 임시 디렉터리를 사용하거나 아래 예시처럼 app 컨테이너에 쓰기 가능한 emptyDir를 마운트하십시오.

spec:
  template:
    spec:
      volumes:
        - name: java-tmp
          emptyDir: {}
      containers:
        - name: app
          volumeMounts:
            - name: java-tmp
              mountPath: /tmp

Java 선택 기능

Metric, Log, Profile 및 Security는 규칙 또는 애플리케이션 환경 변수로 명시적으로 활성화합니다. Security에는 OTEL_LOGS_EXPORTER=otlp가 필요합니다. Profile에는 JFR 지원 런타임, DataKit Profile 수집기 및 별도의 OTEL_PROFILING_ENDPOINT가 필요합니다. 이 기능은 profiler sidecar를 자동으로 추가하지 않습니다. 선택 기능의 호환성은 해당 Beacon 릴리스를 따릅니다.

런타임 요구 사항, 신호 설정 및 내보내기 설정은 Beacon Java 가이드를 참조하십시오. Profile을 DataKit에 전송하려면 OTEL_PROFILING_EXPORTER=datakit도 설정하십시오.

Java 주입 및 트레이스 확인

예시 Deployment가 준비되면 init 컨테이너의 종료 코드와 JVM 옵션을 확인하십시오. 종료 코드는 0이고 기존 JVM 옵션에 -javaagent:/beacon-auto-instrumentation-java/javaagent.jar가 한 번만 추가되어야 합니다.

kubectl -n default rollout status deployment/beacon-java-demo
pod=$(kubectl -n default get pods -l app=beacon-java-demo -o jsonpath='{.items[0].metadata.name}')
kubectl -n default get pod "$pod" -o jsonpath='{.status.initContainerStatuses[?(@.name=="datakit-beacon-lib-init")].state.terminated.exitCode}{"\n"}'
kubectl -n default get pod "$pod" -o jsonpath='{.spec.containers[?(@.name=="app")].env[?(@.name=="JAVA_TOOL_OPTIONS")].value}{"\n"}'
kubectl -n default logs "$pod" -c app

주입되지 않거나 init 컨테이너에 실패하면 공통 문제 해결을 참조하세요. 주입 후에도 트레이스가 없으면 DataKit 수집기, OTLP 주소 및 기존 OTEL_* 또는 JVM -D 옵션을 확인하세요. 롤백하려면 Beacon 규칙을 비활성화하거나 admission.datakit/beacon.enabled: "false"를 설정한 후 Pod를 다시 생성하세요.

DDTrace는 Datadog이 시작하고 오픈 소스로 공개한 트레이싱 프로젝트이며, 관련 저작권은 Datadog 및 기타 기여자에게 있습니다. Guance는 DDTrace 데이터 수신을 지원하며, DDTrace 사용 시 해당 프로젝트의 오픈 소스 라이선스를 따라야 합니다.

문서 평가

이 페이지가 도움이 되었나요?