Ziele erstellen und verwalten

Für jede Instanz des Telemetry Router definieren Sie Ziele, an die Ihr Datenstrom weitergeleitet wird. Sie können den Datenstrom an einen OpenTelemetry-kompatiblen Endpunkt oder an einen S3-kompatiblen STACKIT Object Storage senden. Für OpenTelemetry können entweder Basic- oder Token-Auth verwendet werden, damit sich Ihre Instanz des Telemetry Router gegenüber Ihrem Ziel authentifizieren kann. Den eigentlichen Ziel-Endpunkt definieren Sie mit einer URI.

Voraussetzungen

• Sie verfügen über eine Telemetry Router-Instanz. Instanzen erstellen und verwalten

API-Voraussetzungen & Variablen

Um die API-Befehle in dieser Anleitung auszuführen, müssen Sie zunächst die folgenden Pfadparameter als Umgebungsvariablen in Ihrem Terminal exportieren (oder sie direkt in den Befehlen ersetzen):

• $PROJECT_ID: Ihre eindeutige STACKIT Projekt-ID (z. B. 16dbfb51...).
• $REGION_ID: Die Region, in der sich Ihre Instanz befindet (z. B. eu01 oder eu02).
• $TELEMETRY_ROUTER_ID: Die eindeutige ID Ihrer Telemetry Router-Instanz.
• $DESTINATION_ID: Die spezifische Kennung eines Ziels (erforderlich für die Vorgänge Anzeigen, Bearbeiten und Löschen).

Wenn Sie Hilfe beim Finden dieser Kennungen benötigen oder erfahren möchten, wie der stackit curl-Wrapper funktioniert, lesen Sie unsere zentrale Anleitung: Interagieren mit der Telemetry Router API.

Eine konzeptionelle Übersicht der verschiedenen Authentifizierungspfade finden Sie in unserer Authentifizierungsübersicht.

Ziel-Konfigurationsobjekt

Um ein Ziel zu konfigurieren, müssen Sie eine Ziel-uri, einen Typ und eine Authentifizierung angeben.

STACKIT API

Sie fügen die Zielkonfiguration als JSON-Key namens config zu den entsprechenden Anfragen hinzu. Die folgende Tabelle zeigt die verfügbaren Keys innerhalb dieses Objekts:

Key	Bedeutung	Typ
configType	Typ des Ziels (OpenTelemetry oder S3)	string
openTelemetry	Objekt, das ein OpenTelemetry-Ziel beschreibt. Weitere Informationen finden Sie unter Konfiguration für OpenTelemetry-Ziele.	object
s3	Objekt, das ein S3-Ziel beschreibt. Weitere Informationen finden Sie unter Konfiguration für S3-Ziele.	object
filter	Ein optionales Filter-Objekt. Lesen Sie Filter, um zu erfahren, wie Filter funktionieren.	object

Konfiguration für OpenTelemetry-Ziele

Um ein OpenTelemetry-Ziel zu konfigurieren, ist das openTelemetry-Objekt obligatorisch. Es besteht aus einer URI und Authentifizierungsparametern. Für die Authentifizierung muss entweder basicAuth oder bearerToken angegeben werden.

Key	Bedeutung	Typ
uri	Der tatsächliche Ziel-Endpunkt. Das Limit liegt bei 1024 Zeichen.	string
basicAuth	Ein verschachteltes Objekt, das Informationen zur Authentifizierung Ihrer OpenTelemetry-Instanz gegenüber Ihrem Ziel enthält	Siehe Beispiele unten
bearerToken	Ein Token-String zur Authentifizierung Ihrer OpenTelemetry-Instanz gegenüber Ihrem Ziel	string

Basic-Auth-Objekt

Das Basic-Auth-Objekt besteht aus zwei Keys:

Key	Bedeutung	Typ
username	Der Benutzername für die Authentifizierung gegenüber Ihrem Endpunkt	string
password	Das Passwort für die Authentifizierung gegenüber Ihrem Endpunkt	string

Beispiel für ein Konfigurationsobjekt

{
    "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"
}

Konfiguration für S3-Ziele

Um ein S3-Ziel zu konfigurieren, ist das s3-Objekt obligatorisch. Es besteht aus einer Endpunkt-Bucket-Kombination und Authentifizierungsparametern. Für die Authentifizierung muss ein accessKey angegeben werden.

Key	Bedeutung	Typ
accessKey	Der Zugriffsschlüssel für die Authentifizierung	object
bucket	Die Kennung Ihres Buckets. Das Limit liegt bei 63 Zeichen.	string
endpoint	Die Endpunkt-URI. Das Limit liegt bei 1024 Zeichen.	string

Access-Key-Objekt

Das Access-Key-Objekt besteht aus zwei Keys:

Key	Bedeutung	Typ
id	Die ID Ihres Zugriffsschlüssels	string
secret	Das Secret für die Authentifizierung gegenüber Ihrem S3-Endpunkt	string

Beispiel für ein Konfigurationsobjekt

{

    "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"
}

Ziel erstellen

STACKIT API

Um ein Ziel für den Telemetry Router zu erstellen, müssen Sie den entsprechenden Endpunkt aufrufen.

Eigenschaften für Ihr neues Ziel wählen

Parameter	Bedeutung	Beispiel
config	Ein JSON-Objekt, das das eigentliche Ziel beschreibt	Siehe Ziel-Konfigurationsobjekt
displayName	Ein Name für das Ziel	my-telemetry-destination
description	Eine optionale Beschreibung für Ihre Unterlagen	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>
}'

Beispiel für ein S3-kompatibles Speicherziel

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"
    }
}'

Beispiel für ein OpenTelemetry-Ziel

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

Führen Sie die folgenden Schritte im Portal aus, um ein Telemetry Router-Ziel zu erstellen.

1. Klicken Sie in der Seitenleiste auf Telemetry Router.

2. Navigieren Sie zu der Instanz, für die Sie ein Ziel erstellen möchten, und klicken Sie auf den Eintrag.

3. Klicken Sie in der Seitenleiste auf Ziele.

4. Klicken Sie in der Leiste oben auf Ziel erstellen.

5. Tragen Sie in dem Bereich die erforderlichen Informationen ein.

   Geben Sie einen Namen und eine optionale Beschreibung ein. Als Typ können Sie OpenTelemetry oder S3 Object Storage wählen. Der Typ hängt vom Ziel Ihres Log-Streams ab. Klicken Sie dann auf Weiter.

6. Abhängig von dem Typ, den Sie im vorherigen Schritt gewählt haben, stehen Ihnen in diesem Bereich unterschiedliche Optionen zur Verfügung.

   OpenTelemetry

   Bei einem Ziel vom Typ OpenTelemetry können Sie zwischen Bearer Token und Basic Authentication wählen, um den Telemetry Router gegenüber Ihrem Ziel zu authentifizieren. Für ein Ziel mit dem Typ Bearer Token tragen Sie die Ziel-URI und Ihr Bearer-Token ein. Für ein Ziel mit dem Typ Basic Authentication tragen Sie die Ziel-URI, einen Benutzernamen und ein Passwort ein.

   S3 Object Storage

   Bei einem Ziel vom Typ S3 Object Storage müssen Sie einen Endpunkt, einen Bucket-Namen, eine Access Key ID und ein Access Key Secret angeben. Informationen darüber, wie Sie diese Daten erhalten, finden Sie in der Dokumentation Ihres Object Storage.

7. Nachdem Sie den Kosten zugestimmt haben, klicken Sie auf Kostenpflichtig bestellen, um Ihr Ziel zu erstellen.

Alle Ziele auflisten

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"

Beispiel

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

Führen Sie die folgenden Schritte im Portal aus, um alle Telemetry Router-Ziele aufzulisten.

1. Klicken Sie in der Seitenleiste auf Telemetry Router.
2. Navigieren Sie zu der Instanz, für die Sie ein Ziel erstellen möchten, und klicken Sie auf den Eintrag.
3. Klicken Sie in der Seitenleiste auf Ziele.
4. Sie sehen eine Liste mit allen Ihren Telemetry Router-Zielen.

Ziel anzeigen

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"

Beispiel

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

Führen Sie die folgenden Schritte im Portal aus, um ein Telemetry Router-Ziel anzuzeigen.

1. Klicken Sie in der Seitenleiste auf Telemetry Router.
2. Navigieren Sie zu der Instanz, für die Sie ein Ziel erstellen möchten, und klicken Sie auf den Eintrag.
3. Klicken Sie in der Seitenleiste auf Ziele.
4. Sie sehen eine Liste mit allen Ihren Telemetry Router-Zielen. Navigieren Sie zu dem Eintrag, den Sie anzeigen möchten, und klicken Sie darauf.

Ziel bearbeiten

STACKIT API

Parameter	Bedeutung	Beispiel
displayName	Ein Name für die Telemetry Router-Instanz. In diesem Endpunkt ist der Parameter optional.	my-telemetry-router
description	Eine optionale Beschreibung für Ihre Unterlagen	My Telemetry Router instance
config	Ein Ziel-Konfigurationsobjekt.	Lesen Sie Ziel-Konfigurationsobjekt, um mehr über die Syntax der Zielkonfiguration zu erfahren.

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>
}'

Beispiel für die Bearbeitung eines Ziels zu einem S3-kompatiblen Speicher für eine bestehende Telemetry Router-Instanz

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"
    }
}'

Beispiel für die Bearbeitung eines Ziels zu einem OpenTelemetry-Speicher für eine bestehende Telemetry Router-Instanz

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

Führen Sie die folgenden Schritte im Portal aus, um ein Telemetry Router-Ziel zu bearbeiten.

1. Klicken Sie in der Seitenleiste auf Telemetry Router.
2. Navigieren Sie zu der Instanz, für die Sie ein Ziel erstellen möchten, und klicken Sie auf den Eintrag.
3. Klicken Sie in der Seitenleiste auf Ziele.
4. Sie sehen eine Liste mit allen Ihren Telemetry Router-Zielen. Navigieren Sie zu dem Eintrag, den Sie bearbeiten möchten, und klicken Sie darauf.
5. Bearbeiten Sie in dem neuen Bereich die Eigenschaften, die Sie ändern möchten. Verfügbare Optionen und deren Bedeutung finden Sie unter der Registerkarte STACKIT Portal in Ein Ziel erstellen.

Ziel löschen

STACKIT API

Um ein Telemetry Router-Ziel zu löschen, müssen Sie den DELETE-Endpunkt aufrufen.

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"

Beispiel:

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

Führen Sie die folgenden Schritte im Portal aus, um ein Telemetry Router-Ziel zu löschen.

1. Klicken Sie in der Seitenleiste auf Telemetry Router.
2. Navigieren Sie zu der Instanz, für die Sie ein Ziel erstellen möchten, und klicken Sie auf den Eintrag.
3. Klicken Sie in der Seitenleiste auf Ziele.
4. Sie sehen eine Liste mit allen Ihren Telemetry Router-Zielen. Navigieren Sie zu dem Eintrag, den Sie löschen möchten, und klicken Sie auf sein Drei-Punkte-Menü.
5. Klicken Sie im Menü auf Löschen.
6. Geben Sie in dem neuen Bereich den Namen des Ziels ein und klicken Sie auf Löschen.

Szenarien

Im folgenden ein paar Beispiele, welche bearbeitet und angewendet werden können.

Logs erlauben

Logs können mit Matchers auf basis der angegebenen Attribute erlaubt werden.

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"
  }
}'

Logs filtern

Logs können mit Filtern auf basis der angegebenen Attribute gefiltert werden.

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"
  }
}'