Common configuration¶

These examples assume that the application and DataKit run on the same host. For remote or container deployments, replace 127.0.0.1 with an address reachable from the application and adjust the DataKit listening addresses.

Enable the DataKit input¶

Install DataKit and connect it to the target workspace. For the default installation path, copy the OpenTelemetry sample configuration:

sudo cp /usr/local/datakit/conf.d/samples/opentelemetry.conf.sample \
  /usr/local/datakit/conf.d/opentelemetry.conf

Edit the file and retain the receiver settings below. Update an existing input instead of adding a duplicate:

[[inputs.opentelemetry]]
  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"
  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"

Restart DataKit. HTTP uses the DataKit HTTP service port, 9529 by default. For remote access, adjust the HTTP listening address and gRPC addr, and restrict access with network policies. See the OpenTelemetry input for Kubernetes setup and full configuration.

Service identity and OTLP settings¶

When sending data to DataKit, start with env and version for environment and release identity. To retain other custom resource attributes as tags, add them to the OpenTelemetry input's customer_tags allowlist. Dots in attribute names are converted to underscores.

export OTEL_SERVICE_NAME=order-service
export OTEL_RESOURCE_ATTRIBUTES=env=prod,version=1.0.0
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317

export OTEL_SERVICE_NAME=order-service
export OTEL_RESOURCE_ATTRIBUTES=env=prod,version=1.0.0
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9529/otel

HTTP exporters append /v1/traces, /v1/metrics, or /v1/logs to the shared base endpoint. Keep the /otel prefix for DataKit. DataKit OTLP/HTTP accepts Protobuf only; use http/protobuf.

Signal-specific variables such as OTEL_EXPORTER_OTLP_TRACES_ENDPOINT override the shared endpoint. A signal-specific HTTP endpoint must contain the complete path, such as http://127.0.0.1:9529/otel/v1/traces. Do not append HTTP paths to gRPC endpoints.

Inject these variables into the actual application process. systemd, containers, and PHP-FPM may not inherit the terminal environment. Restart the application after configuration changes. Inject credentials through deployment secrets rather than committing them to source control.

Profiling and Security¶

• Profiling: Enable the DataKit Profile input. The upload endpoint is http://127.0.0.1:9529/profiling/v1/input. Java uses JFR; Python and Node.js use pprof. Setup is included in each language guide.
• Security: Disabled by default. Supported languages use the existing agent and export through OTLP Logs. Follow Security to configure runtime scope and export, then verify records in Logs.

Verify the integration¶

1. Run this command from the application environment to check access to the DataKit HTTP service. It does not verify port 4317 or input activation.

   curl -f http://127.0.0.1:9529/v1/ping
   

2. Launch the application using its language guide. Confirm that the agent loads and no OTLP export errors occur.

3. Send real requests through a supported web framework, HTTP client, or database integration.
4. Open APM > Traces in Guance, select a recent time range, and filter service by the configured service name. Metrics may take an export interval to appear.
5. With profiling enabled, keep the application alive beyond the collection interval, then check APM > Profiling by service name. For Security, check Logs for records from the service.

See Troubleshooting if data is missing.