Skip to content

OpenTelemetry

OpenTelemetry is an open standard for generating, collecting, and transmitting telemetry data such as traces, metrics, and logs. With OpenTelemetry, you can use a unified data model and the OTLP protocol to observe applications running in different languages, frameworks, and runtime environments.

OpenTelemetry Ecosystem Support

TrueWatch has been listed in the official OpenTelemetry Vendors directory. According to the official annotation, TrueWatch is a commercial observability vendor that supports Native OTLP and can natively receive OpenTelemetry telemetry data. With TrueWatch, users can view and analyze trace, metric, and log data generated by OpenTelemetry in a unified manner, and perform correlation analysis by combining infrastructure, APM, and RUM data.

This document describes how to send OpenTelemetry data from your application to DataKit, which then forwards it to TrueWatch:

Application + OpenTelemetry Instrumentation -> OTLP -> DataKit -> TrueWatch

Choosing an Integration Method

Based on the language ecosystem and application modification requirements, choose between Zero-code Instrumentation and SDK Instrumentation:

Integration Method Supported Languages How It Works Use Cases
Zero-code Instrumentation Java, Python, PHP, Node.js, .NET, Go Automatically creates telemetry data for supported frameworks and components via an agent, runtime hook, extension, startup parameter, or compile-time instrumentation. Minimize changes to business code and quickly collect common Web, HTTP, database, and message queue calls.
SDK Instrumentation Go Initialize the OpenTelemetry SDK in the application and use framework instrumentation libraries or APIs to create telemetry data. Need explicit control over the provider, exporter, sampling, resource attributes, and business spans.

Zero-code means minimal or no changes to business logic, but does not imply that installing components, configuring reporting parameters, or restarting the application is unnecessary. Automatic instrumentation only covers supported frameworks and components; important operations within the business can still be supplemented with custom spans, metrics, and attributes via the OpenTelemetry API.

Zero-code Instrumentation

Language Instrumentation Method Integration Document
Java Load the OpenTelemetry Java Agent via the JVM -javaagent parameter. OpenTelemetry Java; Java Extensions
Python Start the application using opentelemetry-instrument and load the corresponding instrumentation packages. OpenTelemetry Python
PHP Provides runtime hooks via the OpenTelemetry PHP extension, and framework calls are collected by Composer instrumentation packages. OpenTelemetry PHP
Node.js Preload the OpenTelemetry automatic instrumentation module via NODE_OPTIONS. OpenTelemetry Node.js
.NET Loads OpenTelemetry .NET Automatic Instrumentation via the CLR Profiler and Startup Hook. OpenTelemetry .NET
Go Uses otelc to automatically inject OpenTelemetry SDK initialization and component instrumentation logic at compile time. OpenTelemetry Go (otelc)
Go Injects OpenTelemetry SDK and instrumentation logic via LoongSuite during go build. OpenTelemetry Go (LoongSuite)

SDK Instrumentation

Language Instrumentation Method Integration Document
Go Initialize the OpenTelemetry Go SDK, OTLP exporter, and context propagator, and install instrumentation libraries for the frameworks or components used. OpenTelemetry Go SDK

Integration Process

The specific installation commands and startup parameters vary by language, but the overall integration process is consistent:

  1. Enable the DataKit OpenTelemetry Collector: Configure the OTLP/HTTP or OTLP/gRPC reception endpoint, restart DataKit, and confirm network reachability.
  2. Enable OpenTelemetry Instrumentation for the Application: Install the agent, extension, automatic instrumentation module, or SDK based on the language.
  3. Configure Data Reporting Parameters: Set the service name, resource attributes, OTLP protocol, DataKit address, sampling, and signal switches.
  4. Restart and Access the Application: Generate real requests to trigger trace and metric data.
  5. Verify Data: In TrueWatch, check services, traces, and metrics, and use the application and DataKit logs to troubleshoot reporting errors.

DataKit OTLP Reception Endpoints

The host-based integration examples in this document use the following endpoints. Replace <DataKit-IP> with the DataKit address accessible to the application:

Protocol Signal Reception Endpoint
OTLP/HTTP + Protobuf Trace http://<DataKit-IP>:9529/otel/v1/traces
OTLP/HTTP + Protobuf Metric http://<DataKit-IP>:9529/otel/v1/metrics
OTLP/HTTP + Protobuf Log http://<DataKit-IP>:9529/otel/v1/logs
OTLP/gRPC Trace, Metric, Log http://<DataKit-IP>:4317

When using a generic OTLP/HTTP base endpoint, you can configure it as:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://<DataKit-IP>:9529/otel"

Exporters that support the standard OTLP environment variables will automatically append /v1/traces, /v1/metrics, or /v1/logs depending on the signal. If you use a signal-specific endpoint, such as OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, you must provide the full URL including /otel/v1/traces.

The OTLP/gRPC endpoint must not be appended with HTTP paths like /v1/traces. If the application and DataKit are not on the same host, you also need to adjust the DataKit listening address, firewall, or other network access controls. Do not expose the OTLP reception port directly to the public network.

For complete DataKit parameter documentation, see OpenTelemetry Collector.

Common Parameter Recommendations

Regardless of the language used, it is recommended to plan the following resource attributes and propagation parameters uniformly:

Parameter or Attribute Purpose Recommendation
service.name Identifies the service; it is the core field for APM service attribution. Use a stable and unique service name; do not use dynamic values such as Pod or process IDs.
deployment.environment.name Identifies the deployment environment. Consistently use agreed values such as dev, test, staging, prod.
service.version Identifies the application version. Use a release version, build version, or commit ID to facilitate performance comparison across versions.
OTEL_RESOURCE_ATTRIBUTES Set resource attributes in bulk. Only include low-cardinality attributes that do not contain sensitive information.
OTEL_PROPAGATORS Controls the cross-service context propagation format. Default to tracecontext,baggage; ensure compatibility across services in the call chain.
Sampling strategy Controls the amount of data collected and the overhead. Full sampling can be used during initial validation; adjust based on traffic, storage, and troubleshooting needs in production.

If custom resource attributes need to be retained as tags in TrueWatch, add them to the DataKit customer_tags allowlist. Dots in attribute names are converted to underscores; for example, team.name becomes team_name.

Verifying Data

After the integration is complete, first access the application endpoints to generate requests, then perform the following checks:

  1. Run curl http://<DataKit-IP>:9529/v1/ping to confirm that the application can reach DataKit.
  2. Check the application startup logs to confirm that the agent, extension, or SDK has been loaded and that there are no OTLP exporter errors.
  3. In TrueWatch, go to APM and query services and traces by service.name.
  4. Metrics are typically exported periodically; wait at least one export cycle before querying.
  5. If no data is found, check the DataKit collector configuration, the network from the application to DataKit, the OTLP protocol, and the reporting endpoint.