Send Traces to the Platform

You can send traces to the Tracing Service using OpenTelemetry SDKs, agents, and the OpenTelemetry Collector.

This quick start shows how to create a pipeline, get a key, and configure an exporter.

Prerequisites

• An IONOS CLOUD account with permissions to create tracing pipelines.
• A tracing pipeline in AVAILABLE state.
• Outbound HTTPS access on port 443.
• An instrumented application, OpenTelemetry SDK, or OpenTelemetry Collector.

1

Create a pipeline

Send a POST request to the Tracing Service API:

curl --location \
--request POST 'https://tracing.de-txl.ionos.com/pipelines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data '{
  "metadata": {},
  "properties": {
    "name": "orders-prod",
    "protocol": "otlp-http"
  }
}'

The response includes the protocol-specific ingestion endpoint and the key. Save both values.

2

API key usage

Use the key returned when you created the pipeline for authentication.

You must generate a new one only in specific cases, such as:

• The key was accidentally shared.
• The key was lost.
• A team member with access left the company.

For authentication:

• OTLP/HTTP exporters must send the key in the apikey header.
• OTLP/gRPC exporters must send the key as apikey metadata.

3

Obtain the pipeline endpoint

After creating a pipeline, use the returned protocol-specific endpoint. Throughout this guide, <tracing-ingestion-endpoint> refers to the ingestion endpoint — a unique hostname generated for that pipeline. It is not the management API host (tracing.<region>.ionos.com) you used to create the pipeline.

For example, the response's otlpEndpoint might look like:

https://<pipeline>-traces.<tenant>.tracing.<region>.ionos.com/v1/traces

Use the returned protocol-specific endpoint:

• For otlp-http: https://<tracing-ingestion-endpoint>/v1/traces
• For otlp-grpc: grpcs://<tracing-ingestion-endpoint>/v1/traces

Configure an exporter

Each exporter requires the pipeline endpoint and the key.

OTLP/HTTP

Use the pipeline otlpEndpoint and send the key in the apikey header.

Example OpenTelemetry Collector configuration:

exporters:
  otlphttp/ionos:
    endpoint: "https://<tracing-ingestion-endpoint>/v1/traces"
    headers:
      apikey: "<API_KEY>"

service:
  pipelines:
    traces:
      exporters: [otlphttp/ionos]

Note: If your exporter expects the full traces path, use the complete pipeline endpoint returned by the API, for example https://<tracing-ingestion-endpoint>/v1/traces.

OTLP/gRPC

Use the pipeline gRPC endpoint and send the key as apikey metadata.

Example OpenTelemetry Collector configuration:

exporters:
  otlp/ionos:
    endpoint: "<tracing-ingestion-endpoint>:443"
    headers:
      apikey: "<API_KEY>"
    tls:
      insecure: false

service:
  pipelines:
    traces:
      exporters: [otlp/ionos]

Note: The customer-facing endpoint is documented as grpcs://<tracing-ingestion-endpoint>. Some SDKs and collectors may still require the host and port format in their local configuration.

OpenTelemetry SDK examples

The following examples show how to configure common OpenTelemetry SDKs to send traces to Tracing Service.

Note: The examples below use an otlp-http pipeline and the customer-facing endpoint https://<tracing-ingestion-endpoint>/v1/traces. If you use an otlp-grpc pipeline, keep the same apikey authentication but switch to the gRPC endpoint.

Go

Set the following environment variables:

export OTEL_SERVICE_NAME="orders-api"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<tracing-ingestion-endpoint>/v1/traces"
export OTEL_EXPORTER_OTLP_HEADERS="apikey=<API_KEY>"

Example SDK setup:

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)

func main() {
    ctx := context.Background()

    exporter, err := otlptracehttp.New(ctx)
    if err != nil {
        log.Fatal(err)
    }

    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exporter),
        sdktrace.WithResource(resource.NewWithAttributes(
            semconv.SchemaURL,
            semconv.ServiceName("orders-api"),
        )),
    )
    defer func() { _ = tp.Shutdown(ctx) }()

    otel.SetTracerProvider(tp)
}

Java

If you use the OpenTelemetry Java agent, configure it with environment variables:

export OTEL_SERVICE_NAME="orders-api"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<tracing-ingestion-endpoint>/v1/traces"
export OTEL_EXPORTER_OTLP_HEADERS="apikey=<API_KEY>"

java -javaagent:/path/to/opentelemetry-javaagent.jar -jar app.jar

Note: If you use the Java SDK directly instead of the Java agent, use the same OTEL_ environment variables in the application runtime.

Python

Set the following environment variables:

export OTEL_SERVICE_NAME="orders-api"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<tracing-ingestion-endpoint>/v1/traces"
export OTEL_EXPORTER_OTLP_HEADERS="apikey=<API_KEY>"

Example SDK setup:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider(
    resource=Resource.create({"service.name": "orders-api"})
)
processor = BatchSpanProcessor(OTLPSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

Node.js

Set the following environment variables:

export OTEL_SERVICE_NAME="orders-api"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<tracing-ingestion-endpoint>/v1/traces"
export OTEL_EXPORTER_OTLP_HEADERS="apikey=<API_KEY>"

Example SDK setup:

const { NodeSDK } = require('@opentelemetry/sdk-node')
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http')

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),
})

sdk.start()

.NET

Set the following environment variables:

export OTEL_SERVICE_NAME="orders-api"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<tracing-ingestion-endpoint>/v1/traces"
export OTEL_EXPORTER_OTLP_HEADERS="apikey=<API_KEY>"

In .NET applications that use OpenTelemetry, the exporter can then use the same runtime configuration through the standard OTEL_ environment variables.

Troubleshooting

1. Verify pipeline state: Confirm the pipeline is AVAILABLE.
2. Invalid key: Check that you copied the latest pipeline key.
3. Connection errors: Verify outbound HTTPS access on port 443.
4. No traces displayed: Confirm that your application is instrumented and exporting spans.
5. Protocol mismatch: Make sure otlp-http exporters use the HTTP endpoint and otlp-grpc exporters use the gRPC endpoint.