Skip to content

OpenTelemetry

OpenTelemetry is a set of open standards for generating, collecting, and transmitting telemetry data such as Trace, Metric, and Log. With OpenTelemetry, applications in different languages, frameworks, and runtime environments can be observed using a unified data model and OTLP protocol.

OpenTelemetry ecosystem support

Guance is listed in the official OpenTelemetry Vendors directory. According to the official classification, Guance is a commercial observability vendor that supports Native OTLP and can receive OpenTelemetry telemetry data directly. Through Guance, users can view and analyze OpenTelemetry Trace, Metric, and Log data in one place, and correlate it with infrastructure, application performance, and user access data.

This document describes how to send the application's OpenTelemetry data to DataKit, and then DataKit reports it to Guance:

Application + OpenTelemetry instrumentation -> OTLP -> DataKit -> Guance

Select access method

Choose Zero-code Instrumentation or SDK Instrumentation based on your language ecosystem and how much application change is acceptable:

Access method Applicable languages How it works Typical scenarios
Zero-code Instrumentation Java, Python, PHP, Node.js, .NET, Go Automatically creates telemetry for supported frameworks and components through agents, runtime hooks, extensions, startup parameters, or compile-time instrumentation. You want to change as little business code as possible and quickly collect common Web, HTTP, database, and message-queue calls.
SDK Instrumentation Go Initialize the OpenTelemetry SDK in the application and create telemetry with instrumentation libraries or the API. You need explicit control over Providers, Exporters, sampling, resource attributes, and custom business spans.

Zero-code means no business-logic changes or only minimal changes. It does not mean you can skip component installation, reporting configuration, or application restarts. Auto-instrumentation only covers supported frameworks and components; important business operations can still be supplemented with custom spans, metrics, and attributes through the OpenTelemetry API.

Zero-code Instrumentation

Language Instrumentation method Documentation
Java Load the OpenTelemetry Java Agent with JVM -javaagent. OpenTelemetry Java; Java extension
Python Start the application through opentelemetry-instrument and load the corresponding instrumentation package. OpenTelemetry Python
PHP Use runtime hooks provided by the OpenTelemetry PHP extension together with Composer instrumentation packages. OpenTelemetry PHP
Node.js Preload OpenTelemetry auto-instrumentation module via NODE_OPTIONS. OpenTelemetry Node.js
.NET Load OpenTelemetry .NET Automatic Instrumentation via CLR Profiler and Startup Hook. OpenTelemetry .NET
Go Inject the OpenTelemetry SDK and instrumentation logic during go build with LoongSuite. OpenTelemetry Go (LoongSuite)

SDK Instrumentation

Language Instrumentation method Documentation
Go Initialize the OpenTelemetry Go SDK, OTLP Exporter, and context propagator, and install instrumentation libraries for the frameworks or components you use. OpenTelemetry Go SDK

Access process

The exact installation commands and startup parameters vary by language, but the overall integration flow is the same:

  1. Enable the DataKit OpenTelemetry collector: configure the OTLP/HTTP or OTLP/gRPC receive endpoint, restart DataKit, and confirm network reachability;
  2. Enable OpenTelemetry instrumentation for the application: install the Agent, extension, auto-instrumentation module, or SDK for the target language;
  3. Configure 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 produce Trace and Metric data;
  5. Verify the data: check services, traces, and metrics in Guance, and use application and DataKit logs to troubleshoot reporting errors.

DataKit OTLP receiving address

The host-based examples in this document use the following addresses. Replace <DataKit-IP> with a DataKit address reachable from your application:

Protocol Signal Receive Address
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 the generic OTLP/HTTP base address, it can be configured as:

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

Exporters that support standard OTLP environment variables will automatically append /v1/traces, /v1/metrics or /v1/logs per signal. If using a signal-specific address, such as OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, you need to fill in the full address including /otel/v1/traces.

OTLP/gRPC addresses cannot be appended with HTTP paths such as /v1/traces. When 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 receiving port directly to the public network.

For complete DataKit parameter description, see OpenTelemetry collector .

Unified parameter recommendation

No matter which language is used, it is recommended to plan the following resource attributes and propagation parameters uniformly:

Parameter or attribute Function Suggestion
service.name Identifies the service and is the core field of APM service ownership. Use stable and unique service names and do not use dynamic values ​​such as Pod and process ID.
deployment.environment.name Identifies the deployment environment. Uniformly use agreed values ​​such as dev, test, staging, prod, etc.
service.version Identifies the application version. Use release, build, or commit IDs to easily compare performance across versions.
OTEL_RESOURCE_ATTRIBUTES Set resource attributes in batches. Only place properties that have low cardinality and do not contain sensitive information.
OTEL_PROPAGATORS Controls propagation of formats across service contexts. By default, tracecontext,baggage is used first, and the services in the calling chain remain compatible.
Sampling strategy Control collection volume and overhead. Full sampling can be performed during the access verification phase; the production environment is adjusted according to traffic, storage and troubleshooting needs.

If you want to keep custom resource attributes as tags in Guance, add them to the DataKit customer_tags whitelist. . in attribute names is converted to _; for example, team.name becomes team_name.

Verification data

After integration is complete, first access the application 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 log to confirm that the Agent, extension, or SDK has been loaded and that there are no OTLP Exporter errors;
  3. In Application Performance Monitoring of Guance, query services and traces by service.name;
  4. Metrics are usually exported periodically, so wait for at least one export cycle before querying;
  5. If no data is returned, check the DataKit collector configuration, network connectivity from the application to DataKit, the OTLP protocol, and the reporting endpoint in order.

Feedback

Is this page helpful? ×