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 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 Promtail/Grafana Agents.

Send and query your first logs

You can send logs via REST API, Promtail, Grafana Agent, or third-party tools.

Below are examples using the Loki API.

Send logs via 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.

Query logs vs 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!"
                    ]
                ]
            }
        ],
      [...]
    }
}