Create and manage destinations of Telemetry Router

For each instance of the Telemetry Router, you define destinations to which your data stream is forwarded. You can send the data stream to an OpenTelemetry-compatible endpoint or to an S3-compatible STACKIT Object Storage. For OpenTelemetry, either Basic or Token Auth can be used so that your Telemetry Router instance can authenticate itself to your destination. You define the actual target endpoint using a URI.

Prerequisites

• You have a Telemetry Router instance Create and manage instances

API Prerequisites & Variables

To execute the API commands in this guide, you must first export the following path parameters as environment variables in your terminal (or replace them directly in the commands):

• $PROJECT_ID: Your unique STACKIT project ID (e.g., 16dbfb51...).
• $REGION_ID: The region where your instance is located (e.g., eu01 or eu02).
• $TELEMETRY_ROUTER_ID: The unique ID of your Telemetry Router instance.
• $DESTINATION_ID: The specific identifier of a destination (required for View, Edit, and Delete operations).

If you need help locating these identifiers or want to learn how the stackit curl wrapper works, refer to our central guide: Interacting with the Telemetry Router API.

For a conceptual overview of the different authentication paths, see our Authentication Overview.

Destination config object

To configure a destination, you need to provide a destination uri, a type and an authentication.

STACKIT API

You add the destination configuration as JSON key called config to the appropriate requests. The following table represents the available keys within this object:

Key	Meaning	Type
configType	Type of the destination (OpenTelemetry or S3)	string
openTelemetry	Object that describes an Open Telemetry destination. Refer to Configuration for Open Telemetry targets for more information.	object
s3	Object that describes a S3 destination. Refer to Configuration for S3 targets for more information.	object
filter	An optional filter object. Read Filter to learn how filters work.	object

Configuration for Open Telemetry targets

To configure an Open Telemetry destination, the openTelemetry object is mandatory. It consists of an URI and authentication parameters. For authentication, either basicAuth or bearerToken must be provided.

Key	Meaning	Type
uri	The actual destination endpoint. It has a limit of 1024 characters.	string
basicAuth	A nested object that holds information to authenticate your Open Telemetry instance against your destination	See examples below
bearerToken	A token string to authenticate your Open Telemetry instance against your destination	string

Basic Auth object

The Basic-Auth object consists of two keys:

Key	Meaning	Type
username	The username to authenticate against your endpoint	string
password	The password to authenticate against your endpoint	string

Example of a config object

{
    "configType": "OpenTelemetry",
    "openTelemetry":
    {
        "basicAuth": {
            "username": "stackit-open-telemetry-client",
            "password": "my-top-secret-password"
        },
        "uri": "https://my-opentelemetry-destination.on-prem-cloud.example.com"
    },
    "displayName": "My Open Telemetry destination"
}

Configuration for S3 targets

To configure a S3 destination, the s3 object is mandatory. It consists of an endpoint-bucket-combination and authentication parameters. For authentication, an accessKey must be provided.

Key	Meaning	Type
accessKey	The access key for authentication	object
bucket	The identifier of your bucket. It has a limit of 63 characters.	string
endpoint	The endpoint URI. It has a limit of 1024 characters.	string

Access key object

The access key object consists of two keys:

Key	Meaning	Type
id	The id of your access key	string
secret	The secret to authenticate against your S3 endpoint	string

Example of a config object

{
    "configType": "S3",
    "s3":
    {
        "accessKey": {
            "id": "stackit-s3-client",
            "secret": "my-secret"
        },
        "bucket": "my-bucket",
        "endpoint": "https://my-s3-bucket.on-prem-cloud.example.com"
    },
    "displayName": "My S3 destination"
}

STACKIT Portal

For instructions on how to manage destination config settings, refer to the STACKIT Portal tab in Create a destination.

Create a destination

STACKIT API

To create a Telemetry Router destination, you need to call the appropriate endpoint.

Choose the properties for your new destination

Parameter	Meaning	Example
config	A JSON object that describes the actual destination	See #destination-config-object
displayName	A name for the destination	my-telemetry-destination
description	An optional description for your reference	My new Telemetry Router destination

stackit curl -X POST \
"https://telemetry-router.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-routers/$TELEMETRY_ROUTER_ID/destinations" \
-H "Content-Type: application/json" \
--data '{
    "displayName": "<DISPLAY_NAME>",
    "description": "<DESCRIPTION>",
    "config": <CONFIG_OBJECT>
}'

Example for an S3-compatible storage destination

stackit curl -X POST \
"https://telemetry-router.api.stackit.cloud/v1/projects/16dbfb51-7a75-42d3-a51d-99f87f48cd32/regions/eu01/telemetry-routers/d5b5cdcc-c155-4d66-82ef-4289db8e4557/destinations" \
-H "Content-Type: application/json" \
--data '{
    "displayName": "my-telemetry-destination",
    "description": "My telemetry destination",
    "config": {
        "configType": "S3",
        "s3": {
            "accessKey": {
                "id": "stackit-s3-client",
                "secret": "my-secret"
            },
            "bucket": "my-bucket",
            "endpoint": "https://my-s3-bucket.on-prem-cloud.example.com"
        },
        "displayName": "My S3 destination"
    }
}'

Example for an OpenTelemetry destination

stackit curl -X POST \
"https://telemetry-router.api.stackit.cloud/v1/projects/16dbfb51-7a75-42d3-a51d-99f87f48cd32/regions/eu01/telemetry-routers/d5b5cdcc-c155-4d66-82ef-4289db8e4557/destinations" \
-H "Content-Type: application/json" \
--data '{
    "displayName": "my-telemetry-destination",
    "description": "My telemetry destination",
    "config": {
        "configType": "OpenTelemetry",
        "openTelemetry": {
            "basicAuth": {
                "username": "stackit-open-telemetry-client",
                "password": "my-top-secret-password"
            },
            "uri": "https://my-opentelemetry-destination.on-prem-cloud.example.com"
        },
        "displayName": "My Open Telemetry destination"
    }
}'

STACKIT Portal

Follow the steps in the Portal to create a Telemetry Router destination.

1. On the sidebar, click on Telemetry Router.

2. Navigate to the instance, for that you want to create a destination and click on the entry.

3. On the sidebar, click on Destinations.

4. On the bar on the top, click on Create destination.

5. On the pane, fill in the needed information.

   Fill in a name and an optional description. As type you can choose OpenTelemetry or S3 Object Storage. The type depends on the target of your log stream. Then click on Next.

6. Depending on the type you have chosen in the step before, you have different options in this pane.

   OpenTelemetry

   With an OpenTelemtry type target, you can choose between Bearer Token and Basic authentication to authenticate the Telemetry Router against your target. For a target with the type Bearer Token, fill in the destination URI and your Bearer token. For a target with the type Basic authentication, fill in the destination URI, a username and a password.

   S3 Object Storage

   With an S3 Object Storage type target, you need to provide an Endpoint, a Bucket-name, an Access Key ID and an Access Key Secret. Refer to the documentation of your Object Storage on how to acquire those information.

7. After agreeing to the costs, click on Order fee-based to create your destination.

List all destinations

STACKIT API

stackit curl -X GET \
"https://telemetry-router.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-routers/$TELEMETRY_ROUTER_ID/destinations" \
-H "Content-Type: application/json"

Example

stackit curl -X GET \
"https://telemetry-router.api.stackit.cloud/v1/projects/16dbfb51-7a75-42d3-a51d-99f87f48cd32/regions/eu01/telemetry-routers/d5b5cdcc-c155-4d66-82ef-4289db8e4557/destinations" \
-H "Content-Type: application/json"

STACKIT Portal

Follow the steps in the Portal to list all Telemetry Router destinations.

1. On the sidebar, click on Telemetry Router.
2. Navigate to the instance, for that you want to create a destination and click on the entry.
3. On the sidebar, click on Destinations.
4. You see a list with all your Telemetry Router destinations.

View a destination

STACKIT API

stackit curl -X GET \
"https://telemetry-router.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-routers/$TELEMETRY_ROUTER_ID/destinations/$DESTINATION_ID" \
-H "Content-Type: application/json"

Example

stackit curl -X GET \
"https://telemetry-router.api.stackit.cloud/v1/projects/16dbfb51-7a75-42d3-a51d-99f87f48cd32/regions/eu01/telemetry-routers/d5b5cdcc-c155-4d66-82ef-4289db8e4557/destinations/60e59099-8209-4b69-a553-239fd79038a3" \
-H "Content-Type: application/json"

STACKIT Portal

Follow the steps in the Portal to view a Telemetry Router destination.

1. On the sidebar, click on Telemetry Router.
2. Navigate to the instance, for that you want to create a destination and click on the entry.
3. On the sidebar, click on Destinations.
4. You see a list with all your Telemetry Router destinations. Navigate to the entry you want to view and click on it.

Edit a destination

STACKIT API

Parameter	Meaning	Example
displayName	A name for the Telemetry Router instance. In this endpoint, the parameter is optional.	my-telemetry-router
description	An optional description for your reference	My Telemetry Router instance
config	An destination config object.	Read Destination config object to learn about the destination config syntax.

stackit curl -X PUT \
"https://telemetry-router.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-routers/$TELEMETRY_ROUTER_ID/destinations/$DESTINATION_ID" \
-H "Content-Type: application/json" \
--data '{
    "displayName": "<DISPLAY_NAME>",
    "description": "<DESCRIPTION>",
    "config": <CONFIG_OBJECT>
}'

Example of editing a destination to an S3 compatible storage to an existing Telemetry Router instance

stackit curl -X PUT \
"https://telemetry-router.api.stackit.cloud/v1/projects/16dbfb51-7a75-42d3-a51d-99f87f48cd32/regions/eu01/telemetry-routers/d5b5cdcc-c155-4d66-82ef-4289db8e4557/destinations/60e59099-8209-4b69-a553-239fd79038a3" \
-H "Content-Type: application/json" \
--data '{
    "config": {
        "configType": "S3",
        "s3": {
            "accessKey": {
                "id": "stackit-s3-client",
                "secret": "my-secret"
            },
            "bucket": "my-bucket",
            "endpoint": "https://my-s3-bucket.on-prem-cloud.example.com"
        },
        "displayName": "My S3 destination"
    }
}'

Example of editing a destination to an OpenTelemetry storage to an existing Telemetry Router instance

stackit curl -X PUT \
"https://telemetry-router.api.stackit.cloud/v1/projects/16dbfb51-7a75-42d3-a51d-99f87f48cd32/regions/eu01/telemetry-routers/d5b5cdcc-c155-4d66-82ef-4289db8e4557/destinations/60e59099-8209-4b69-a553-239fd79038a3" \
-H "Content-Type: application/json" \
--data '{
    "config": {
        "configType": "OpenTelemetry",
        "openTelemetry": {
            "basicAuth": {
                "username": "stackit-open-telemetry-client",
                "password": "my-top-secret-password"
            },
            "uri": "https://my-opentelemetry-destination.on-prem-cloud.example.com"
        },
        "displayName": "My Open Telemetry destination"
    }
}'

STACKIT Portal

Follow the steps in the Portal to edit a Telemetry Router destination.

1. On the sidebar, click on Telemetry Router.
2. Navigate to the instance, for that you want to create a destination and click on the entry.
3. On the sidebar, click on Destinations.
4. You see a list with all your Telemetry Router destinations. Navigate to the entry you want to edit and click on it.
5. On the new pane, edit the properties you want to change. Refer to the STACKIT Portal tab in Create a destination for available options and their meaning.

Delete a destination

STACKIT API

To delete a Telemetry Router destination, you need to call the DELETE endpoint.

stackit curl -X DELETE \
"https://telemetry-router.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-routers/$TELEMETRY_ROUTER_ID/destinations/$DESTINATION_ID" \
-H "Content-Type: application/json"

Example:

stackit curl -X DELETE \
"https://telemetry-router.api.stackit.cloud/v1/projects/16dbfb51-7a75-42d3-a51d-99f87f48cd32/regions/eu01/telemetry-routers/d5b5cdcc-c155-4d66-82ef-4289db8e4557/destinations/60e59099-8209-4b69-a553-239fd79038a3" \
-H "Content-Type: application/json"

STACKIT Portal

Follow the steps in the Portal to delete a Telemetry Router destination.

1. On the sidebar, click on Telemetry Router.
2. Navigate to the instance, for that you want to create a destination and click on the entry.
3. On the sidebar, click on Destinations.
4. You see a list with all your Telemetry Router destinations. Navigate to the entry you want to delete and click on its three-dots-menu.
5. On the menu, click on Delete.
6. On the new pane, enter the name of the destination and click on Delete.

Use cases

The following shows a view real world use cases that can be modified and applied.

Matching logs

Logs can be matched with matchers based on the provided attributes.

stackit curl -X POST \
"https://telemetry-router.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-routers/$TELEMETRY_ROUTER_ID/destinations" \
-H "Content-Type: application/json" \
--data '{
  "name": "secrets-manager-destination",
  "description": "Forwards only logs originating from the secrets-manager service",
  "type": "OTLP",
  "config": {
    "configType": "OpenTelemetry",
    "filter": {
      "attributes": [
        {
          "key": "service.name",
          "level": "logRecord",
          "matcher": "=",
          "values": [
            "secrets-manager"
          ]
        }
      ]
    },
    "uri": "https://my-opentelemetry-destination.logs.eu01.onstackit.cloud/otlp/v1/logs",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6ImE1NTZmYWI0MWY2YzQ1MGY3ZDU5YzRmNGVkNWI0NmMxIn0.eyJub3RpY2UiOiJDb25ncmF0dWxhdGlvbnMhIFlvdSBoYXZlIGRlY29kZWQgYSBiZWFyZXIgdG9rZW4gbWVhbnQgZm9yIGRlbW9uc3RyYXRpb24gcHVycG9zZXMuIFdlIGF0IFNUQUNLSVQgZW1waGFzaXplIHNlY3VyaXR5IGFuZCBkYXRhIGludGVncml0eS4gUGxlYXNlIHVzZSB5b3VyIG93biBhY2Nlc3MgdG9rZW4gZm9yIHlvdXIgcmVzb3VyY2VzLiJ9.LPOHfT45JNOpTSh_q6x4pDRVK052QwUwSFU9tLPB6gGrYjf4dTKjWJ-2aRdd2LlWsxO5y0it89VsZpbzVRvI5Q"
  }
}'

Filtering logs

Logs can be filtered with matchers based on the provided attributes.

stackit curl -X POST \
"https://telemetry-router.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-routers/$TELEMETRY_ROUTER_ID/destinations" \
-H "Content-Type: application/json" \
--data '{
  "name": "secrets-manager-destination",
  "description": "Forwards only logs originating from the secrets-manager service",
  "type": "OTLP",
  "config": {
    "configType": "OpenTelemetry",
    "filter": {
      "attributes": [
        {
          "key": "service.name",
          "level": "logRecord",
          "matcher": "!=",
          "values": [
            "secrets-manager"
          ]
        }
      ]
    },
    "uri": "https://my-opentelemetry-destination.logs.eu01.onstackit.cloud/otlp/v1/logs",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6ImE1NTZmYWI0MWY2YzQ1MGY3ZDU5YzRmNGVkNWI0NmMxIn0.eyJub3RpY2UiOiJDb25ncmF0dWxhdGlvbnMhIFlvdSBoYXZlIGRlY29kZWQgYSBiZWFyZXIgdG9rZW4gbWVhbnQgZm9yIGRlbW9uc3RyYXRpb24gcHVycG9zZXMuIFdlIGF0IFNUQUNLSVQgZW1waGFzaXplIHNlY3VyaXR5IGFuZCBkYXRhIGludGVncml0eS4gUGxlYXNlIHVzZSB5b3VyIG93biBhY2Nlc3MgdG9rZW4gZm9yIHlvdXIgcmVzb3VyY2VzLiJ9.LPOHfT45JNOpTSh_q6x4pDRVK052QwUwSFU9tLPB6gGrYjf4dTKjWJ-2aRdd2LlWsxO5y0it89VsZpbzVRvI5Q"
  }
}'