Create your first STACKIT Logs instance and send your first log messages

Prerequisites

• You have a STACKIT customer account: Create a customer account
• You have a STACKIT user account: Create a user account
• You have a STACKIT project: Create a project

Prepare, order and create an instance

In this Getting started you will create an instance and configure it. This guide shows the most common settings for a small developer environment. When following this guide, you will work with the STACKIT Portal.

1. Visit the STACKIT Portal.
2. On the sidebar click on Logs.
3. On the bar on the top click on Create Logs.

After completing the steps, you see an overlay with three sections (General information and Setup).

General information

• Enter the name for the instance.

Setup

• Enter the retention days for the instance.

• Add your clients IPv4 address to the list of ACLs.

  If you want to connect with the computer, with which you are browsing these docs, use Cloudflare’s IP trace tool to determine your IPv4 address. Open your browser of choice and visit the Cloudflare Trace Tool. Copy the value behind ip. It should look like xxx.xxx.xxx.xxx. Now append /32 to it and add it as ACL entry. To do so, click on Add IP Range and paste it in the field.

If you don’t add your clients IPv4 address to the list of ACLs, you won’t be able to connect to your instance!

After reviewing every setting, click on Order fee-based to create your new instance. Then you will see a confirmation that your instance is created. Your new instance will be added to the list of instances. After a few minutes it will switch from Reconciling to Active.

Performing the action described here may incur costs or change your ongoing costs. Please check carefully what one-time and/or ongoing costs will be charged, and only perform the actions if you agree and are authorized to do so.

Retrieve API URLs

You will need these URLs for API access and clients like Grafana Alloy. Once the instance is Active:

1. Click your Logs instance.
2. Open the API tab.
3. Open the Info tab.
4. On the sidebar click on API.
5. You will see different URLs exposed by Logs instance.

Here is a small summary of these URLs:

• Data source: This is the root URL of the Logs instance.
• OTLP ingest: This is the URL which OTLP clients will use to write data.
• Ingest: This the URL which Loki API clients will use to write data.
• Query range: This is the URL which clients like Grafana will use to read logs over a specific time range.
• Query: This is the URL which clients like Grafana will use to read logs over a specific time range.

Different collectors expect different “depths” of the URL. Providing the full path to a client that appends its own path will cause 404 Not Found errors. See documentation of the client and then use the appropriate URL.

Retrieve credentials

Once the instance is Active:

1. Click your Logs instance.

2. Open the API tab.

3. Open the Access tokens tab.

4. Click Create access token.

5. Enter Name.

6. Select Unlimited lifetime.

   Unlimited lifetime is not recommended for production use.

7. Select Role Read and Write.

8. Click Create.

9. Store the Token at a secure space.

   This information cannot be retrieved later.

You will need these for API access and clients like Grafana Alloy.

Sending logs

STACKIT Logs supports logs ingestion with Grafana Loki API or OpenTelemetry logs over HTTP. There are many clients which can be used to send logs to STACKIT Logs instance e.g. Grafana Alloy, OpenTelemetry Collector etc. See How-tos section of STACKIT Logs for examples of these clients usage.

Write logs via cURL

Below is an example of sending data via Loki API using cURL.

Parameter	Meaning	Example
InstanceId	The instance id of your Logs instance.	e074181e-5a2c-4515-9980-af03bee08922
AccessToken	The access token you just created	eyJhbGc…
AppName	The name of you app in Loki	demo-app
Timestamp	The start timespan of logs	1763294137000000000

curl
  -X POST https://[InstanceId].logs.eu01.onstackit.cloud/loki/api/v1/push \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [AccessToken]" \
  --data '{
            "streams": [
              {
                "stream": {
                  "app": "[AppName]",
                  "level": "info"
                },
                "values": [
                  [ [Timestamp], "Hello from STACKIT Logs!" ]
                ]
              }
            ]
          }'

You should get a 204 No Content Response.

Querying logs

STACKIT Logs exposes the stored logs via Loki API over HTTP. This can be used to read and visualize logs data in Grafana. See How-tos guide for visualizing logs in Grafana.

Read logs via cURL

Below is an example of querying logs data via Loki API using cURL.

Parameter	Meaning	Example
InstanceId	The instance id of your Logs instance.	e074181e-5a2c-4515-9980-af03bee08922
AccessToken	The access token you just created	eyJhbGc…
AppName	The name of you app in Loki	demo-app
Start	The start timespan of logs	1763294136000000000
End	The end timespan of logs	1763294138000000000

curl
  -X POST https://[InstanceId].logs.eu01.onstackit.cloud/loki/api/v1/query_range?query={app="[AppName]"}&end=[End]&start=[Start] \
  -H "Authorization: Bearer [AccessToken]"

Logs should answer with the logs which is similar to:

{
    "status": "success",
    "data": {
        "resultType": "streams",
        "result": [
            {
                "stream": {
                    "app": "demo-app",
                    "detected_level": "info",
                    "level": "info",
                    "service_name": "demo-app"
                },
                "values": [
                    [
                        "1763294137000000000",
                        "Hello from STACKIT Logs!"
                    ]
                ]
            }
        ],
      [...]
    }
}