> 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/api-reference/observability/tracing-service/tracing-api-workflows.md).

# Tracing API Workflows

Use these end-to-end workflows to deploy, connect, and operate resources using the IONOS CLOUD Tracing API.

* **Deploy a pipeline:** Plan your pipeline configuration and provision it through to the `AVAILABLE` state.
* **Connect to your pipeline:** Retrieve the OTLP ingestion endpoint and Grafana endpoint, and connect your exporter using the credentials from deploy.
* **Operate a pipeline:** Manage a running pipeline with day-to-day operations and deprovision it when no longer needed.

> **Note:** If an operation returns an error, refer to the response details of each operation for API-specific error codes. For generic HTTP status codes used across IONOS CLOUD APIs, see [HTTP Status Codes](https://docs.ionos.com/cloud/api-reference/readme/getting-started#http-status-codes).

### Deploy a Pipeline

Use this workflow to plan and provision a new pipeline.

#### Prerequisites

* An access token that authenticates your API requests. For more information, see [Authentication](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/authentication.md).

#### Step 1: Choose Protocol

Choose the OTLP protocol for your pipeline.

* `otlp-http`: Use for OTLP HTTP exporters. Exporters must append `/v1/traces` to the `otlpEndpoint` when sending traces.
* `otlp-grpc`: Use for OTLP gRPC exporters. Exporters connect to the `otlpEndpoint` on port 443 without a URL path.

> **Note:** Changing the protocol after creation reprovisions the ingestion route behind the same DNS name and may temporarily interrupt ingestion while you reconfigure your exporter.

#### Step 2: Provision a Pipeline

1. **Create the pipeline:**
   * **API:** [Create Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/create-pipeline)
   * **Action:** Provide the required fields: `properties.name` (1-36 characters) and `properties.protocol` (`otlp-grpc` or `otlp-http`). Example request body:

```json
{
  "properties": {
    "name": "trace-pipeline-prod",
    "protocol": "otlp-grpc"
  }
}
```

* **Result:** The API returns HTTP `201` with the pipeline `id` and `metadata.state` as `PROVISIONING`. Note the `id` and `metadata.key`. You need them in every subsequent operation.

> **Note:**
>
> * Pipeline provisioning is asynchronous. Poll [Retrieve Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/retrieve-pipeline) until `metadata.state` is `AVAILABLE`.
> * Once `AVAILABLE`, `metadata.otlpEndpoint` contains the stable ingestion endpoint and `metadata.grafanaEndpoint` contains the Grafana URL.
> * Save `metadata.key`: the API returns it only in this response and in the [Rotate Key](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/key/rotate-key) response. You cannot retrieve it later.
> * If `metadata.state` returns `FAILED`, retrieve the pipeline using [Retrieve Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/retrieve-pipeline) and inspect `metadata.statusMessage` for details. Submit a new [Create Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/create-pipeline) request to retry. Failed pipelines cannot be recovered in place.

**Next steps:** To connect your exporter to the pipeline, see [Connect to Your Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/tracing-api-workflows.md).

### Connect to Your Pipeline

Use this workflow to retrieve the pipeline ingestion endpoint and connect your OTLP exporter.

#### Prerequisites

* Ensure the pipeline is in the `AVAILABLE` state.
* You must have the `id` (UUID) of the pipeline. You receive this when you complete the [Deploy a Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/tracing-api-workflows.md) workflow.
* You must have the `metadata.key` you saved in Step 2 of the [Deploy a Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/tracing-api-workflows.md) workflow.

#### Step 1: Retrieve the Connection Details

* **API:** [Retrieve Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/retrieve-pipeline)
* **Path Parameter `pipelineId`:** The UUID of your pipeline.
* **Action:** Retrieve the pipeline to obtain the OTLP ingestion endpoint and Grafana URL.
* **Result:** The API returns HTTP `200` with the full pipeline object. Note `metadata.otlpEndpoint` and `metadata.grafanaEndpoint` for Step 2.

#### Step 2: Connect Your OTLP Exporter

Use the following details to configure your OTLP exporter:

| Property          | Value                                                            |
| ----------------- | ---------------------------------------------------------------- |
| **Endpoint**      | `metadata.otlpEndpoint` from Step 1                              |
| **Authorization** | `Bearer <metadata.key>` from the deploy or key rotation response |
| **Protocol**      | Matches `properties.protocol`: `otlp-http` or `otlp-grpc`        |

> **Note:** For OTLP HTTP exporters, append `/v1/traces` to the `otlpEndpoint`. For OTLP gRPC exporters, use the `otlpEndpoint` on port 443 without a URL path.

**Next steps:** For day-2 tasks on a running pipeline, see [Operate a Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/tracing-api-workflows.md).

### Operate a Pipeline

Use this workflow to perform day-2 tasks on a running pipeline.

> **Note:** All pipeline updates use Ensure (full-replacement) semantics. Retrieve the full pipeline configuration before you submit any `PUT` request. Any field omitted is set to its schema default or cleared to empty. It does not retain its previous value.

#### Prerequisites

* Ensure the pipeline is in the `AVAILABLE` state.
* You must have the `id` (UUID) of the pipeline. You receive this when you complete [Deploy a Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/tracing-api-workflows.md).

#### Update Pipeline Configuration

Change the pipeline name or OTLP protocol using the Ensure operation.

* **API:** [Ensure Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/ensure-pipeline)
* **Path Parameter `pipelineId`:** The UUID of the pipeline.
* **Action:** Submit the full pipeline object with updated `properties.name` or `properties.protocol`. Both fields must be present in every request.
* **Result:** The API returns HTTP `200` and the pipeline transitions to `UPDATING`, then back to `AVAILABLE`. Poll [Retrieve Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/retrieve-pipeline) on `metadata.state` to confirm.

> **Note:** If `metadata.state` returns `FAILED`, retrieve the pipeline using [Retrieve Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/retrieve-pipeline) and inspect `metadata.statusMessage` for details. Submit a new [Ensure Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/ensure-pipeline) request to retry.

#### Rotate the Pipeline Key

Generate a new authentication key to invalidate the current key.

* **API:** [Rotate Key](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/key/rotate-key)
* **Path Parameter `pipelineId`:** The UUID of the pipeline.
* **Action:** Submit the rotate key request. No request body is required.
* **Result:** The API returns HTTP `201` with the new `key` value. Save this key: the API returns it only in this response, and you cannot retrieve it again.

> **Note:** Update your OTLP exporter configuration with the new key immediately after rotation. Rotation invalidates the previous key, and exporters using it stop sending traces.

#### Deprovision the Pipeline

> **Warning:** Deleting a pipeline is irreversible. The delete operation permanently removes the pipeline and all associated ingestion configuration.

Deprovision the pipeline when it is no longer needed to release resources.

* **API:** [Delete Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/delete-pipeline)
* **Path Parameter `pipelineId`:** The UUID of the pipeline to delete.
* **Action:** Submit the delete request to permanently remove the pipeline.
* **Result:** The API returns HTTP `202` and accepts the delete request. Deletion is asynchronous, and it permanently removes the pipeline and all associated resources. You cannot recover them.

> **Note:** If `metadata.state` returns `FAILED` instead of the pipeline being removed, retrieve the pipeline using [Retrieve Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/retrieve-pipeline) and inspect `metadata.statusMessage` for details. Submit a new [Delete Pipeline](https://docs.ionos.com/cloud/api-reference/observability/tracing-service/pipelines/delete-pipeline) request to retry.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ionos.com/cloud/api-reference/observability/tracing-service/tracing-api-workflows.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
