> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/observability/tracing-service/quick-start/send-traces-to-platform.md).

# 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 <code class="expression">space.vars.ionos\_cloud</code> 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.

{% stepper %}
{% step %}

## Create a pipeline

Send a `POST` request to the Tracing Service API:

```bash
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.
{% endstep %}

{% step %}

## 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.
  {% endstep %}

{% step %}

## 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`
  {% endstep %}
  {% endstepper %}

## Configure an exporter

Each exporter requires the pipeline endpoint and the `key`.

{% tabs %}
{% tab title="OTLP/HTTP" %}
Use the pipeline `otlpEndpoint` and send the key in the `apikey` header.

Example OpenTelemetry Collector configuration:

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

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

{% hint style="info" %}
**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`.
{% endhint %}
{% endtab %}

{% tab title="OTLP/gRPC" %}
Use the pipeline gRPC endpoint and send the key as `apikey` metadata.

Example OpenTelemetry Collector configuration:

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

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

{% hint style="info" %}
**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.
{% endhint %}
{% endtab %}
{% endtabs %}

## OpenTelemetry SDK examples

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

{% hint style="info" %}
**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.
{% endhint %}

{% tabs %}
{% tab title="Go" %}
Set the following environment variables:

```bash
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:

```go
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)
}
```

{% endtab %}

{% tab title="Java" %}
If you use the OpenTelemetry Java agent, configure it with environment variables:

```bash
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
```

{% hint style="info" %}
**Note:** If you use the Java SDK directly instead of the Java agent, use the same `OTEL_` environment variables in the application runtime.
{% endhint %}
{% endtab %}

{% tab title="Python" %}
Set the following environment variables:

```bash
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:

```python
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)
```

{% endtab %}

{% tab title="Node.js" %}
Set the following environment variables:

```bash
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:

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

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

sdk.start()
```

{% endtab %}

{% tab title=".NET" %}
Set the following environment variables:

```bash
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.
{% endtab %}
{% endtabs %}

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ionos.com/cloud/observability/tracing-service/quick-start/send-traces-to-platform.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.