Migrate Go OpenTelemetry APM

Overview

The OpenTelemetry Go SDK provides APIs for manual trace instrumentation and automatic instrumentation via contrib libraries. This page covers installing the SDK, initializing a tracer provider, creating spans, and configuring the OTLP exporter to send traces to Kloudfuse.

Install

Run these commands to install the core Go packages:

go get go.opentelemetry.io/otel \
  go.opentelemetry.io/otel/trace \
  go.opentelemetry.io/otel/sdk \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

Set Up Instrumentation

Initialize a tracer provider with the OTLP HTTP exporter at application startup. Call this before creating any spans:

package main

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/otel/sdk/trace"
)

func initTracer(ctx context.Context) (*trace.TracerProvider, error) {
    exporter, err := otlptracehttp.New(ctx)
    if err != nil {
        return nil, err
    }
    tp := trace.NewTracerProvider(trace.WithBatcher(exporter))
    otel.SetTracerProvider(tp)
    return tp, nil
}
go

To create a span in your application code:

tracer := otel.Tracer("my-service")
ctx, span := tracer.Start(context.Background(), "my-operation")
defer span.End()
go

For the full setup guide see OpenTelemetry Go Instrumentation.

Send to Kloudfuse

Configure the OTLP exporter by setting the following environment variables before starting your application:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<kloudfuse-hostname>/ingester/otlp"   (1)
export OTEL_EXPORTER_OTLP_HEADERS="Kf-Api-Key=<api-key>"                          (2)
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production"
1 Replace <kloudfuse-hostname> with your Kloudfuse cluster hostname.
2 Replace <api-key> with your Kloudfuse API key.

Instrumentation Libraries

OpenTelemetry Go provides contrib packages that automatically instrument popular libraries and frameworks. Review the OpenTelemetry Registry for Go for available packages.

To install a contrib instrumentation package:

go get go.opentelemetry.io/contrib/instrumentation/{import-path}/otel{package-name}

Troubleshooting

No Traces in Kloudfuse

  1. Verify the endpoint URL is correct and includes the /ingester/otlp path.

  2. Check the Kf-Api-Key header value in OTEL_EXPORTER_OTLP_HEADERS.

  3. Enable SDK logging to see export errors:

    export OTEL_LOG_LEVEL=debug

Spans Not Being Recorded

Ensure otel.SetTracerProvider(tp) is called before any call to otel.Tracer(…​). If the global tracer provider is not set, spans are created with a no-op tracer and silently discarded.

TLS or Connection Errors

If your Kloudfuse endpoint uses a self-signed certificate, configure TLS settings on the exporter directly rather than disabling verification globally. Confirm the hostname resolves and port 443 is reachable from your host.

External References