OTEL service

Quickwit natively supports the OpenTelemetry Protocol (OTLP) and provides a gRPC endpoint to receive spans from an OpenTelemetry collector, or from your application directly, via an exporter. This endpoint is enabled by default.

When enabled, Quickwit will start the gRPC service ready to receive spans from an OpenTelemetry collector. The spans are indexed on the otel-trace-v0 index, and this index will be automatically created if not present. The index doc mapping is described in the next section.

If for any reason, you want to disable this endpoint, you can:

• Set the QW_ENABLE_OTLP_ENDPOINT environment variable to false when starting Quickwit.
• Or configure the node config by setting the indexer setting enable_otlp_endpoint to false.

node-config.yaml

# ... Indexer configuration ...
indexer:
    enable_otlp_endpoint: false

Trace and span data model

A trace is a collection of spans that represents a single request. A span represents a single operation within a trace. OpenTelemetry collectors send spans, Quickwit then indexes them in the otel-trace-v0 index that maps OpenTelemetry span model to an indexed document in Quickwit.

The span model is derived from the OpenTelemetry specification.

Below is the doc mapping of the otel-trace-v0 index:

version: 0.6

index_id: otel-trace-v0

doc_mapping:
  mode: strict
  field_mappings:
    - name: trace_id
      type: text
      tokenizer: raw
      fast: true
    - name: trace_state
      type: text
      indexed: false
    - name: service_name
      type: text
      tokenizer: raw
    - name: resource_attributes
      type: json
      tokenizer: raw
    - name: resource_dropped_attributes_count
      type: u64
      indexed: false
    - name: scope_name
      type: text
      indexed: false
    - name: scope_version
      type: text
      indexed: false
    - name: scope_attributes
      type: json
      indexed: false
    - name: scope_dropped_attributes_count
      type: u64
      indexed: false
    - name: span_id
      type: text
      tokenizer: raw
    - name: span_kind
      type: u64
    - name: span_name
      type: text
      tokenizer: raw
    - name: span_fingerprint
      type: text
      tokenizer: raw
    - name: span_start_timestamp_nanos
      type: u64
      indexed: false
    - name: span_end_timestamp_nanos
      type: u64
      indexed: false
    - name: span_start_timestamp_secs
      type: datetime
      input_formats: [unix_timestamp]
      indexed: false
      fast: true
      precision: seconds
      stored: false
    - name: span_duration_millis
      type: u64
      indexed: false
      fast: true
      stored: false
    - name: span_attributes
      type: json
      tokenizer: raw
    - name: span_dropped_attributes_count
      type: u64
      indexed: false
    - name: span_dropped_events_count
      type: u64
      indexed: false
    - name: span_dropped_links_count
      type: u64
      indexed: false
    - name: span_status
      type: json
      indexed: false
    - name: parent_span_id
      type: text
      indexed: false
    - name: events
      type: array<json>
      tokenizer: raw
    - name: event_names
      type: array<text>
      tokenizer: default
      record: position
      stored: false
    - name: links
      type: array<json>
      tokenizer: raw

  timestamp_field: span_start_timestamp_secs

indexing_settings:
  commit_timeout_secs: 5

search_settings:
  default_search_fields: []

Known limitations

There are a few limitations on the current distributed tracing setup in Quickwit 0.5:

• Aggregations are not available on sparse fields and JSON field, this will be fixed in 0.6. This means that only the timestamp and trace_id fields can support aggregations.
• The OTLP gRPC service does not provide High-Availability and High-Durability, this will be fixed in Q2/Q3.
• OTLP gRPC service index documents only in the otel-trace-v0 index.
• OTLP HTTP is not available but it should be easy to add.

If you are interested in new features or discovered other limitations, please open an issue on GitHub.