How to push metrics

This guide explains the process of setting up application metrics scraping, configuring the export via Grafana Alloy, and ensuring secure transmission to your STACKIT Observability Instance using the Prometheus Remote Write protocol.

Prerequisites

Before you can push metrics to your STACKIT Observability instance, ensure you have the following ready:

• Technical Credentials: You need a technical <USERNAME> and <PASSWORD> for your specific instance. If you haven’t generated these yet, follow the instructions in our Authentication Overview.
• Metrics Source: You must have an application or service exposing metrics (e.g., via a /metrics endpoint in standard Prometheus format).

In the configuration examples below, you will need to replace <USERNAME>, <PASSWORD>, and <METRICS_ENDPOINT_URL> with your specific details.

If you need help locating your endpoint URLs, refer to our guide on Locating your identifiers and Endpoint URLs.

The Metrics Data Flow

Metrics follow a specific path from your application to the STACKIT backend. As shown in the diagram below, this guide focuses on using Grafana Alloy as the recommended agent to collect and forward your data. However, the STACKIT architecture is highly flexible; you can alternatively use other OpenTelemetry tools, such as the native Prometheus agent or Telegraf, to push metrics to your STACKIT Observability backend.

• Application: Your application exposes a local endpoint (usually /metrics) containing the current state of its internal counters and gauges.
• Grafana Alloy (Agent): The local agent periodically “scrapes” (pulls) this endpoint to collect the latest metrics data.
• STACKIT Observability Endpoint (Prometheus): Grafana Alloy securely “pushes” the collected metrics in batches to the specific Remote Write ingestion endpoint in your STACKIT instance, where they are stored and made available for querying.

Grafana Alloy Configuration Example

Grafana Alloy is the recommended method for collecting metrics and managing secure authentication. This example shows a simple configuration (config.alloy) that scrapes a local application and forwards the data securely to the STACKIT endpoint.

If you are sending metrics from multiple servers or environments, we highly recommend adding external_labels (e.g., env = "production") to your remote write configuration so your data does not get mixed up in Grafana.

config.alloy

config.alloy

// 1. Scrape metrics from a local target
prometheus.scrape "local_app" {
  targets = [
    {"__address__" = "localhost:8080"}, // Replace with your app's metrics port
  ]

  // Forward the scraped metrics to the remote_write block below
  forward_to = [prometheus.remote_write.stackit_instance.receiver]
  scrape_interval = "60s"
}

// 2. Push metrics to STACKIT Observability
prometheus.remote_write "stackit_instance" {
  endpoint {
    # IMPORTANT: Copy the full "Metrics Remote Write" URL from the STACKIT Portal
    url = "<METRICS_ENDPOINT_URL>"

    # Required for Basic Authentication
    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }

  // Best Practice: Add labels to distinguish metrics from different servers
  external_labels = {
    env = "production",
    cluster = "eu01"
  }
}

docker-compose.yaml

Use this Docker Compose file to run Grafana Alloy in a Docker container. It mounts your local config.alloy file into the container and starts the agent. The Alloy UI and API are accessible over port 12345.

docker-compose.yaml

services:
  alloy:
    image: grafana/alloy:latest
    container_name: alloy
    command:
      - run
      - --server.http.listen-addr=0.0.0.0:12345
      - --storage.path=/var/lib/alloy/data
      - /etc/alloy/config.alloy
    ports:
      - "12345:12345"
    volumes:
      - ./config.alloy:/etc/alloy/config.alloy:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - alloy-data:/var/lib/alloy/data
    restart: unless-stopped

volumes:
  alloy-data:

Check Metrics

Once everything is running, open Grafana in your STACKIT Observability instance and go to Explore. Select your Metrics data source and run a query (for example, up) to confirm that your data is successfully arriving.