Documentation Grafana Cloud Instrument and send data Logs Configure Loki settings

Introduction

Loki offers many settings (also known as limits) that can be adjusted for different use cases. In Grafana Cloud Logs, we manage them all for you, and set defaults that work for most of our users. Still there may be some settings you may need to adjust such as retention, the OTLP label mappings, or enabling truncation of long log lines that would otherwise be dropped.

If this is your case, you can use the configuration self-serve API to set these configurations to the values you need.

How to configure your settings

Prerequisites

You need the following information to use the Grafana Cloud API:

• Cloud Logs Instance URL and user ID. To find this information, refer to Find instance endpoint.
• API token with logs write permissions. For more information about scopes, refer to Grafana Cloud Access Policies.

Hereafter, replace <LOKI_URL> with your Cloud Logs Instance URL, <LOKI_TENANT> for your user ID, and <LOKI_TOKEN> for your API key.

API reference

Configure new settings

Copy

PUT <LOKI_URL>/loki/api/v1/config/limits/<LIMIT_NAME>
Authorization: Bearer <LOKI_TENANT>:<LOKI_TOKEN>
Content-Type: application/yaml

Where <LIMIT_NAME> is the name of the limit you want to set. The body of the request should contain the values for the limit. You can optionally pass a metadata field with an author name.

Refer to the Supported settings and restrictions section for examples.

Get configured settings

Copy

GET <LOKI_URL>/loki/api/v1/config/limits/<LIMIT_NAME>
Authorization: Bearer <LOKI_TENANT>:<LOKI_TOKEN>

This endpoint returns:

• The configured value for the limit (if any).
• The status: applied if the changes are applied already, pending if the values have not been applied yet, or pending-too-long if the requested values have been in pending state for longer than expected.
• Other metadata about the last successful PUT request such as the author, timestamp and request ID.

Get applied settings

Copy

GET <LOKI_URL>/loki/api/v1/config/limits/applied
Authorization: Bearer <LOKI_TENANT>:<LOKI_TOKEN>

Returns the configurable settings that Grafana Cloud Logs is applying to your tenant. Until the requested settings are applied, this endpoint may show different values from the ones you configured.

Supported settings and restrictions

Here is a list of the limits that can be configured via the APIs described above along with the restrictions that apply to each.

Configure retention

By default, Grafana Cloud Logs has a retention of 30 days. You can increase it via the retention_period or retention_stream limits.

You can learn more about retention in the Log retention documentation.

Here are some examples. First for configuring the global retention period:

Bash Copy

curl -X PUT \
  -H "Authorization: Bearer <LOKI_TENANT>:<LOKI_TOKEN>" \
  -H "Content-Type: application/yaml" \
  --data-binary @retention_period.yaml \
  <LOKI_URL>/loki/api/v1/config/limits/retention_period

YAML Copy

# retention_period.yaml
retention_period: 90d
metadata:
  author: 'john@email.com'

And for stream retention:

Bash Copy

curl -X PUT \
  -H "Authorization: Bearer <LOKI_TENANT>:<LOKI_TOKEN>" \
  -H "Content-Type: application/yaml" \
  --data-binary @retention_stream.yaml \
  <LOKI_URL>/loki/api/v1/config/limits/retention_stream

YAML Copy

# retention_stream.yaml
retention_stream:
  - period: 90d
    selector: '{env="prod"}'
  - period: 60d
    selector: '{env="dev"}'
metadata:
  author: 'john@email.com'

Restrictions

• You cannot decrease the retention below the currently configured/applied (or 30 days by default).
• The maximum configurable retention period is 1 year.
• The period must be a multiple of 30 days (for example 60d, 90d, etc.).

Set max line truncation

By default, Grafana Cloud Logs drops all log lines that exceed the maximum log line size. You can enable max_line_size_truncate (refer to the limits configuration docs) to truncate the lines that exceed the maximum log line size instead of dropping the logs.

Bash Copy

curl -X PUT \
  -H "Authorization: Bearer <LOKI_TENANT>:<LOKI_TOKEN>" \
  -H "Content-Type: application/yaml" \
  --data-binary @max_line_size_truncate.yaml \
  <LOKI_URL>/loki/api/v1/config/limits/max_line_size_truncate

YAML Copy

# max_line_size_truncate.yaml
max_line_size_truncate: true
metadata:
  author: 'john@email.com'

OTLP label mappings

Grafana Cloud Logs configures a default set of OpenTelemetry resource labels mapping to steam labels. If you need to modify the labels mapping, you can configure them using this API.

Bash Copy

curl -X PUT \
  -H "Authorization: Bearer <LOKI_TENANT>:<LOKI_TOKEN>" \
  -H "Content-Type: application/yaml" \
  --data-binary @otlp_config.yaml \
  <LOKI_URL>/loki/api/v1/config/limits/otlp_config

YAML Copy

# otlp_config.yaml
otlp_config:
  resource_attributes:
    attributes_config:
      - action: index_label
        attributes: [region, cluster]
      - action: structured_metadata
        attributes: [pod]
      - action: drop
        attributes: [owner]
  scope_attributes:
    - action: structured_metadata
      attributes: [team, experiment]
    - action: drop
      regex: 'java_jdk_*'
  log_attributes:
    - action: structured_metadata
      attributes: [email]
    - action: drop
      attributes: [password]
metadata:
  author: 'john@email.com'

Restrictions

• The severity_text_as_label field cannot be set to true.
• You can promote up to 30 resource attributes to stream labels (that is the attributes with action: index_label).