1 of 7

API How-Tos

The Logging Service offers regional APIs that enable programmatic interaction with the platform. These APIs serve various purposes: task automation, system integration, and platform functionality extension. Additionally, the APIs allow you to filter logs based on different criteria, such as the date range, log level, and source.

Regional REST API endpoint

A regional endpoint is necessary to interact with the Logging Service REST API endpoints. Currently, IONOS supports only the following endpoint for the Berlin region:

https://logging.de-txl.ionos.com/pipelines

Request parameter headers

To interact with the Logging Service REST API endpoints, the header must contain the following values:

Header

Required

Type

Description

Here are some of the most common API How-Tos for the Logging Service:

We recommend you refer to the following after creating an instance via the API:

Set Up a Logging Pipeline Instance

It is necessary to create an instance of the logging pipeline before sending log data to the Logging Service platform. For more information, see Log Pipelines.

When sending a request to create a logging pipeline, you can specify a unique tag of your choice for each log source. For more information about the complete list of available sources, see Log Sources.

This topic contains the following sections:

Request to create a logging pipeline
Sample response
Create a pipeline with custom labels

Request to create a logging pipeline

The following request creates an instance of a logging pipeline with two log streams: docker and kubernetes.

curl --location \ 
--request POST 'https://logging.de-txl.ionos.com/pipelines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data '{
  "properties": {
    "name": "demo",
    "logs": [
      {
        "source": "docker",
        "tag": "dock",
        "protocol": "tcp",
        "labels": [
          "label1d"
        ],
        "destinations": [
          {
            "type": "loki",
            "retentionInDays": 7
          }
        ]
      }, 
            {
             "source": "kubernetes",
             "tag": "k8s",
             "protocol": "tcp",
            "destinations":  
            [
              {
              "type": "loki",
              "retentionInDays": 14
              }
            ]
           }
    ]
  }
}'

Response

The following is a sample response. The values returned by each response differ based on the request.

{
    "id": "aaaaa-bbbb-1234-cccc-dddd",
    "type": "Pipeline",
    "metadata": {
        "createdDate": "2023-10-19T11:48:31Z",
        "createdBy": "abc@ionos.com",
        "createdByUserId": "ID",
        "createdByUserUuid": "UUID",
        "lastModifiedDate": "2023-10-19T11:48:31Z",
        "lastModifiedBy": "abc@ionos.com",
        "lastModifiedByUserId": "ID",
        "lastModifiedByUserUuid": "UUID",
        "status": "PROVISIONING"
    },
    "properties": {
        "name": "demo",
        "logs": [
            {
                "public": true,
                "source": "docker",
                "tag": "dock",
                "destinations": [
                    {
                        "type": "loki",
                        "retentionInDays": 7
                    }
                ],
                "labels": [
                    "label1d"
                ],
                "protocol": "tcp"
            },
            {
                "public": true,
                "source": "kubernetes",
                "tag": "k8s",
                "destinations": [
                    {
                        "type": "loki",
                        "retentionInDays": 14
                    }
                ],
                "protocol": "tcp"
            }
        ],
        "tcpAddress": "",
        "httpAddress": "",
        "grafanaAddress": "",
        "key": "key"
    }
}

You may notice that the pipeline's status is temporarily set to the PROVISIONING state while provisioning is in process. A GET request retrieves information about the pipeline and its status. For more information, see Retrieve logging pipeline information.

Create a pipeline with custom labels

Log sources like Kubernetes, Docker, and Linux Systemd collect and offer relevant labels. You can use these labels to analyze reports and query the dashboard. However, if you want to label additional fields from the log sources, you can define custom labels as follows when you create a pipeline:

curl --location \ 
--request POST 'https://logging.de-txl.ionos.com/pipelines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data '{
    "properties": {
        "name": "demo",
        "logs": [
            {
                "source": "docker",
                "tag": "dock",
                "protocol": "tcp",
                "labels": [
                    "label1",
                    "label2"
                ]
            }
        ]
    }
}'

Obtain a new Key

A key is necessary to send logs over the logging pipeline. For more information about the purpose of a pipeline key, see Log Security.

Warning:

IONOS adheres to a Share Once policy to generate a key; there is no alternative method to retrieve it if lost. Hence, we recommend that you secure the generated key.
The previous key is instantly revoked when you generate a new key for a specific pipeline.

Request

To get a new key for a pipeline, you can use the following request. Remember to replace the {pipelineID} with a valid ID of a pipeline to access its key.

curl --location
--request POST 'https://logging.de-txl.ionos.com/pipelines/{pipelineID}/key' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN'

Response

The response contains the key necessary to configure the Shared_Key in Fluent Bit.

{
  "key": "key123"
}

Modify a Logging Pipeline Instance

You can modify your logging pipeline by sending a PATCH request with a specific pipeline ID.

Note: To modify a logging pipeline, you can use the same payload that you use in the POST request for creating a logging pipeline. For more information, see Set Up a Logging Pipeline Instance.

The following is a sample request. Remember to replace the {pipelineID} with a valid ID of the respective logging pipeline.

curl --location \
--request PATCH 'https://logging.de-txl.ionos.com/pipelines/{pipelineID}' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "properties": {
        "name": "new-logging-name",
        "logs": [
            {
                "source": "kubernetes1",
                "tag": "kub1",
                "protocol": "tcp",
                "destinations": [
                    {
                        "type": "loki",
                        "retentionInDays": 7
                    }
                ]
            }
        ]
    }
}'

Retrieve Logging Pipeline Information

To retrieve your logging pipeline information, you need the ID of the respective pipeline.

Request

The following is a sample request. Remember to replace the {pipelineID} with a valid ID of the specific pipeline whose information you want to access.

Response

If your request is successful, you will receive the relevant information on a Ready pipeline.

To access logs using Fluent Bit, you need the following information:

Delete a Logging Pipeline Instance

To delete your logging pipeline, you need the ID of the respective pipeline.

Request

The following is a sample request. Remember to replace the {pipelineID} with a valid ID of the specific pipeline that must be deleted.

Response

Modify the Log Retention Policy

Each log stream in your pipeline is initially assigned a default data retention policy of 30 days. The logs for each log stream are retained for the specified number of days. However, you can define a custom retention policy for each log stream. The available options for retention periods include 7, 14, and 30 days.

Note: You can alternatively use the PATCH request to update the retention policy of an existing pipeline.

The following is an example:

curl --location \
--request POST 'https://logging.de-txl.ionos.com/pipelines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data '{
          "properties": {
    "name": "demo",
    "logs": [
      {
        "source": "kubernetes",
        "protocol": "http",
        "tag": "k8s",
        "destinations": [
          {
            "type": "loki",
            "retentionInDays": 7
          }
        ]
      }
    ]
  }
}'

Set Up a Logging Pipeline Instance

It is necessary to create an instance of the logging pipeline before sending log data to the Logging Service platform. For more information, see Log Pipelines.

This topic contains the following sections:

Request to create a logging pipeline
Sample response
Create a pipeline with custom labels

Request to create a logging pipeline

The following request creates an instance of a logging pipeline with two log streams: docker and kubernetes.

curl --location \ 
--request POST 'https://logging.de-txl.ionos.com/pipelines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data '{
  "properties": {
    "name": "demo",
    "logs": [
      {
        "source": "docker",
        "tag": "dock",
        "protocol": "tcp",
        "labels": [
          "label1d"
        ],
        "destinations": [
          {
            "type": "loki",
            "retentionInDays": 7
          }
        ]
      }, 
            {
             "source": "kubernetes",
             "tag": "k8s",
             "protocol": "tcp",
            "destinations":  
            [
              {
              "type": "loki",
              "retentionInDays": 14
              }
            ]
           }
    ]
  }
}'

Response

The following is a sample response. The values returned by each response differ based on the request.

{
    "id": "aaaaa-bbbb-1234-cccc-dddd",
    "type": "Pipeline",
    "metadata": {
        "createdDate": "2023-10-19T11:48:31Z",
        "createdBy": "abc@ionos.com",
        "createdByUserId": "ID",
        "createdByUserUuid": "UUID",
        "lastModifiedDate": "2023-10-19T11:48:31Z",
        "lastModifiedBy": "abc@ionos.com",
        "lastModifiedByUserId": "ID",
        "lastModifiedByUserUuid": "UUID",
        "status": "PROVISIONING"
    },
    "properties": {
        "name": "demo",
        "logs": [
            {
                "public": true,
                "source": "docker",
                "tag": "dock",
                "destinations": [
                    {
                        "type": "loki",
                        "retentionInDays": 7
                    }
                ],
                "labels": [
                    "label1d"
                ],
                "protocol": "tcp"
            },
            {
                "public": true,
                "source": "kubernetes",
                "tag": "k8s",
                "destinations": [
                    {
                        "type": "loki",
                        "retentionInDays": 14
                    }
                ],
                "protocol": "tcp"
            }
        ],
        "tcpAddress": "",
        "httpAddress": "",
        "grafanaAddress": "",
        "key": "key"
    }
}

Create a pipeline with custom labels

curl --location \ 
--request POST 'https://logging.de-txl.ionos.com/pipelines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data '{
    "properties": {
        "name": "demo",
        "logs": [
            {
                "source": "docker",
                "tag": "dock",
                "protocol": "tcp",
                "labels": [
                    "label1",
                    "label2"
                ]
            }
        ]
    }
}'