Documentation Grafana Cloud Instrument and send data Logs Configure Loki settings - API

Configure Loki settings using the API

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.

You can configure these settings using the self-serve API.

Before you begin

To configure Loki settings using the self-serve API, you need the following information:

• 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.

Use the API

Configure new settings

Bash 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

Bash 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

Bash 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 using the API, 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. If you need to set a retention of something less than 30 days, contact Grafana Support.

• When using the API, you cannot decrease the retention below the currently configured or applied value (or 30 days by default). The UI allows retention reduction with an explicit confirmation step.
• The maximum configurable retention period is 1 year.
• The period must be a multiple of 30 days (for example 60d, 90d, etc.).

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

Configure retention using the API

You cannot decrease the retention below the currently configured or applied retention through the self-service API (or 30 days by default).

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'

OTLP label mappings

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

Restrictions:

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

Use the API to map labels

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'

Move mapped resource attributes from indexed labels to structured metadata

In cases where resource attributes that are part of the default mapping have high cardinality and should not be stored as indexed labels, but as structured metadata instead, you must use both the drop stage to remove them from the indexed labels and the structured_metadata stage to add them as structured metadata.

A common example is the service.instance.id resource attribute, which tends to have relatively high cardinality.

Using the API:

YAML Copy

# otlp_config.yaml
otlp_config:
  resource_attributes:
    attributes_config:
      - action: drop
        attributes: [service.instance.id]
      - action: structured_metadata
        attributes: [service.instance.id]

Set max line truncation

By default, Grafana Cloud Logs drops all log lines that exceed the maximum log line size, 256KB. 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.

Use the API to truncate lines

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'