> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Loki

> Forward Control Plane org logs natively to Grafana Loki or any Loki-compatible backend over the Loki push API.

## Overview

[Grafana Loki](https://grafana.com/oss/loki/) is a horizontally scalable, multi-tenant log aggregation system. Control Plane can forward all Org logs natively to any Loki-compatible target — a self-hosted Loki, [Grafana Cloud Logs](https://grafana.com/products/cloud/logs/), or any backend that accepts the Loki push API — using the native Loki output rather than a generic protocol.

Because logs are sent over the native Loki API, Control Plane log metadata is attached as indexed Loki [labels](#forwarded-log-labels) (including `service_name`, which drives Grafana's service detection), so logs are immediately queryable by workload, GVC, location, and more.

Follow the steps below to configure log shipping to Loki.

## Step 1 - Prerequisites

* **Endpoint**: A reachable URL for your Loki instance (see [Endpoint Format](#endpoint-format)).
* **Authentication** (optional): A [Username & Password Secret](/reference/secret#username-and-password) for HTTP basic auth, if your Loki target requires it (Grafana Cloud and most hosted Loki services do).
* **Tenant ID** (optional): The tenant identifier for multi-tenant Loki deployments (for example, the user/instance ID for Grafana Cloud).

## Step 2 - Configure External Logging

External logging can be configured by using either the [UI Console](#enable-logging-using-the-ui-console) or [CLI](#enable-logging-using-the-cli).

### Enable Logging using the UI Console

1. From the Control Plane Console UI, click on `Org` in the left menu.
2. Click `External Logs` in the middle context menu.
3. Select `Loki` and fill out the endpoint, and the credentials and tenant ID if your target requires them.
4. Click `Save`.
5. After the configuration is complete, log entries will begin forwarding to Loki within a few minutes.

### Enable Logging using the CLI

The external logging configuration can be created / updated using the CLI's `cpln org patch ORG_NAME -f FILE.yaml` command.

Below is an example of an [Org](/reference/org) manifest (in YAML). Edit and save the YAML as a file and use it as an input to the CLI's `cpln org patch ORG_NAME -f FILE.yaml` command.

* Substitute: `ORG_NAME`, the `endpoint`, and (if required) `USERPASS_SECRET` and `tenantId`.

```yaml YAML theme={null}
kind: org
name: ORG_NAME
spec:
  logging:
    loki:
      endpoint: https://logs-prod-001.grafana.net
      credentials: //secret/USERPASS_SECRET
      tenantId: "123456"
```

`credentials` and `tenantId` are both optional. Provide whichever your target requires (or neither for an unauthenticated, single-tenant endpoint).

## Endpoint Format

The `endpoint` is required. TLS, the port, and the push path are derived from its format:

| Endpoint                     | TLS | Port                 | Push URI                               |
| ---------------------------- | --- | -------------------- | -------------------------------------- |
| `https://host[:port][/path]` | On  | From URL, else `443` | The URL path, else `/loki/api/v1/push` |
| `http://host[:port][/path]`  | Off | From URL, else `80`  | The URL path, else `/loki/api/v1/push` |
| `host[:port]`                | On  | As given, else `443` | `/loki/api/v1/push`                    |

<Tip>Provide the base URL (for example `https://logs-prod-001.grafana.net`) and Control Plane will append the default `/loki/api/v1/push` path. Include an explicit path only if your target uses a non-standard push endpoint.</Tip>

## Authentication

If your Loki target requires authentication, set `credentials` to a [Username & Password Secret](/reference/secret#username-and-password). The username and password are sent as HTTP basic auth on every push request. For Grafana Cloud, the username is your instance/user ID and the password is a Grafana Cloud access token.

Omit `credentials` for an unauthenticated endpoint, such as a Loki instance reachable only on a trusted internal network.

## Multi-Tenant Loki

For multi-tenant Loki deployments, set `tenantId` to the tenant the logs should be written under. It is sent as the tenant ID on each push request. Leave it unset for single-tenant Loki.

## Forwarded Log Labels

Each forwarded record carries the Control Plane log metadata as indexed Loki labels, and the log message body as the log line:

| Label          | Description                                      |
| -------------- | ------------------------------------------------ |
| `service_name` | Workload name (drives Grafana service detection) |
| `workload`     | Workload name                                    |
| `org`          | Org name                                         |
| `gvc`          | GVC name                                         |
| `location`     | Location the log originated from                 |
| `provider`     | Cloud provider                                   |
| `version`      | Workload version                                 |
| `container`    | Container name                                   |
| `stream`       | Output stream (`stdout` or `stderr`)             |
| `replica`      | Replica name                                     |

<Note>All logs continue to remain accessible through Control Plane, adhering to the [current log retention policy](/core/logs#log-retention).</Note>