lokiexporter

Loki Exporter

Status
Stability	beta: logs
Distributions	contrib
Issues
Code Owners	@gramidt, @gouthamve, @jpkrohling, @mar4uk

Exports data via HTTP to Loki.

Getting Started

The following settings are required:

• endpoint (no default): The target URL to send Loki log streams to (e.g.: http://loki:3100/loki/api/v1/push).
• default_labels_enabled (optional): The map that allows to disable default labels: exporter, job, instance, level. If default_labels_enabled is omitted then default labels will be added. If one of the labels is omitted in default_labels_enabled then this label will be added. Important to remember: If all default labels are disabled and there are no other labels added then the log entry would be dropped because at least one label should be present to successfully put the log record into Loki. The metric otelcol_lokiexporter_send_failed_due_to_missing_labels shows how many log records were dropped because no labels were specified

Example:

exporters:
  loki:
    endpoint: https://loki.example.com:3100/loki/api/v1/push
    default_labels_enabled:
      exporter: false
      job: true

Configuration via attribute hints

Labels

The Loki exporter can convert OTLP resource and log attributes into Loki labels, which are indexed. For that, you need to configure hints, specifying which attributes should be placed as labels. The hints are themselves attributes and will be ignored when exporting to Loki. The following example uses the attributes processor to hint the Loki exporter to set the event.domain attribute as label and the resource processor to give a hint to the Loki exporter to set the service.name as label.

processors:
  attributes:
    actions:
      - action: insert
        key: loki.attribute.labels
        value: event.domain

  resource:
    attributes:
      - action: insert
        key: loki.resource.labels
        value: service.name

Currently, Loki does not support label names with dots. That's why lokiexporter normalizes label names to follow Prometheus label names standard before sending requests to Loki. More information on label normalization could be found here

The promotion of multiple resource and log attributes to labels is done with single action with comma-separated desired labels:

processors:
  attributes:
    actions:
      - action: insert
        key: loki.attribute.labels
        value: event.domain, event.name

  resource:
    attributes:
      - action: insert
        key: loki.resource.labels
        value: service.name, service.namespace

Default labels are always set unless they are disabled with default_labels_enabled setting:

• job=service.namespace/service.name
• instance=service.instance.id
• exporter=OTLP
• level=severity

If service.name and service.namespace are present then job=service.namespace/service.name is set

If service.name is present and service.namespace is not present then job=service.name is set

If service.name is not present and service.namespace is present then job label is not set

If service.instance.id is present then instance=service.instance.id is set

If service.instance.id is not present then instance label is not set

The full list of settings exposed for this exporter are documented here with detailed sample configurations here.

More information on how to send logs to Grafana Loki using the OpenTelemetry Collector could be found here

Tenant information

It is recommended to use the header_setter extension to configure the tenant information to send to Loki. In case a static tenant should be used, you can make use of the headers option for regular HTTP client settings, like the following:

exporters:
  loki:
    endpoint: http://localhost:3100/loki/api/v1/push
    headers:
      "X-Scope-OrgID": acme

It is also possible to provide the loki.tenant attribute hint that specifies which resource or log attributes value should be used as a tenant. For example:

processors:
  resource:
    attributes:
    - action: insert
      key: loki.tenant
      value: host.name

In this case the value of the host.name resource attribute is used to group logs by tenant and send requests with the X-Scope-OrgID header set to relevant tenants.

If the loki.tenant hint attribute is present in both resource and log attributes, then the look-up for a tenant value from resource attributes takes precedence.

Format

To choose the format used for writing log lines by the exporter use the loki.format hint. For example:

processors:
  resource:
    attributes:
    - action: insert
      key: loki.format
      value: logfmt

The following formats are supported:

• logfmt: Write logs as logfmt lines.
• json: Write logs as JSON objects. It is the default format if no hint is present.
• raw: Write the body of the log message as string representation.

Severity

OpenTelemetry uses record.severity to track log levels where loki uses record.attributes.level for the same. The exporter automatically maps the two, except if a "level" attribute already exists.

Advanced Configuration

Several helper files are leveraged to provide additional capabilities automatically:

• HTTP settings
• Queuing and retry settings