Loki Logging Plugin

The Loki Log plugin enables pushing logs to your Loki server.

Setup

To add the Loki logging plugin to your Zuplo project, add the following code to your zuplo.runtime.ts file.

modules/zuplo.runtime.ts(ts)
 
import {
  RuntimeExtensions,
  LokiLoggingPlugin,
  environment,
} from "@zuplo/runtime";

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addPlugin(
    new LokiLoggingPlugin({
      // This is the URL of your Loki server
      url: "https://logs-prod-us-central1.grafana.net/loki/api/v1/push",
      username: "my-username",
      job: "my-api",
      password: environment.LOKI_PASSWORD,
      version: 2,
      fields: {
        field1: "value1",
        field2: "value2",
      },
    }),
  );
}

Configuration Options

The LokiLoggingPlugin constructor accepts an options object with the following properties:

• url - (required) The URL of the Loki server (e.g., https://logs-prod-us-central1.grafana.net/loki/api/v1/push)
• username - (required) Username for authentication
• password - (required) Password for authentication
• version - (optional) The version of the Loki transport to use. Version 2 includes tracing information in log values
• job - (optional) Job name to include in the log stream. Defaults to "zuplo"
• fields - (optional) Custom fields to include in each log entry. Can contain string, number, or boolean values

Custom Fields

Any custom fields you want to include in the log entry can be added to the fields property. These values will be appended to every log entry.

Version Configuration

Setting the version option to 2 changes the log stream to not include the requestId value in the stream, but rather include it as a log value with other tracing information.

Default Fields

Every log entry will have a timestamp and structured data. The structure varies based on the version configuration.

Stream Labels (all versions)

• job - The name of the log stream job. Defaults to "zuplo"
• level - The log level (e.g., ERROR, INFO, DEBUG, WARN)
• environmentType - Where the Zuplo API is running. Values are edge, working-copy, or local
• environmentStage - The deployment stage: working-copy, preview, or production

Log Fields (version 2+)

When using version 2 or later, the following fields are included in the log values:

• requestId - The UUID of the request (the value of the zp-rid header)
• atomicCounter - An atomic counter used to order logs with identical timestamps
• rayId - The network provider identifier (e.g., Cloudflare Ray ID) of the request

Log Format

The shape of the logs sent from Zuplo will be in the following format. If using version 2, tracing info (requestId, etc.) will be included in the log values.

Code(json)
 
{
  "streams": [
    {
      "stream": {
        "job": "zuplo",
        "level": "debug",
        "environmentType": "local",
        "environmentStage": "local"
      },
      "values": [
        [
          "1712254635666000000",
          "Request received '/hello-world'",
          {
            "requestId": "9b9cd3fd-b0fa-455f-b894-4a5c2c9d131b",
            "rayId": "1235567",
            "atomicCounter": 123435346
          }
        ],
        [
          "1712254635666000000",
          "{\"method\":\"GET\",\"url\":\"/hello-world\",\"hostname\":\"localhost\",\"route\":\"/hello-world\"}",
          {
            "requestId": "9b9cd3fd-b0fa-455f-b894-4a5c2c9d131b",
            "rayId": "1235567",
            "atomicCounter": 123435347
          }
        ]
      ]
    }
  ]
}