Adapters

Cruncher supports a flexible adapter system, allowing you to connect to and query data from a variety of sources. Adapters are responsible for connecting to external systems, extracting fields, and providing data to Cruncher in a unified format.

What is an Adapter?

An adapter is a module that knows how to communicate with a specific backend or data source (such as Grafana Loki, Docker logs, or mocked/test data). It extracts fields from the source data and exposes them to Cruncher for querying and analysis.

Built-in Adapters

Cruncher comes with seven built-in adapters to connect with various log sources and data backends:

🔷

Grafana Loki Browser

grafana_browser

Query Loki through a Grafana instance with browser-based authentication. Best if your Loki is hosted in Grafana.

📡

Loki Direct

loki

Query Loki directly without a Grafana wrapper. Ideal for standalone Loki deployments or programmatic access.

☸️

Kubernetes

k8s

Query pod logs from your Kubernetes cluster. Access logs directly from your cluster without external services.

🐳

Docker

docker

Stream logs from local Docker containers. Query container logs running on your machine.

🌐

Coralogix

coralogix

Connect to the Coralogix observability platform. Query logs stored in Coralogix.

🐶

Datadog

datadog

Query logs from the Datadog observability platform using browser-session authentication. Supports index filtering, facet autocomplete, and live mode.

🎲

Mocked Data

mocked_data

Generate sample data locally for testing and demos. No backend needed — perfect for learning QQL.

Configuring Adapters

Adapters are configured in the Cruncher config file (~/.config/cruncher/cruncher.config.yaml). Each adapter entry specifies the type, name, and any required parameters. For example:

connectors:
  - type: grafana_browser
    name: my_grafana
    params:
      grafanaUrl: https://grafana.example.com
      uid: loki-data-source-uid
      # ...other params...
  - type: docker
    name: local_docker
    # ...params...
  - type: mocked_data
    name: test_data

See the configuration reference for the complete structure and each adapter’s documentation for specific parameter details.

How Adapters Work

Field Extraction: Adapters parse incoming data and extract fields, assigning types to each (string, number, boolean, etc.).
Server-side Filtering: Controller parameters in your QQL queries are passed to the adapter, allowing efficient filtering before data arrives.
Unified Processing: Once data is loaded, you can use all of Cruncher’s QQL features to analyze and transform it.

Writing Your Own Adapter

Cruncher is designed to be extensible. You can implement your own adapter by following the patterns in the packages/adapters/ directory. Custom adapters must implement the required interface for data extraction, field typing, and the controller API.

The query() method receives a QueryOptions object that includes an isLiveQuery flag:

interface QueryOptions {
  fromTime: Date;
  toTime: Date;
  limit: number;
  isLiveQuery: boolean;   // true when called from live-mode polling
  cancelToken: AbortSignal;
  onBatchDone: (data: ProcessedData[]) => void;
}

Use isLiveQuery to differentiate between an initial full-range data load (false) and a live-mode incremental poll (true). For live queries, only return new events since the last poll rather than re-fetching the entire range.

See the create-adapter tool for a guided workflow to scaffold a new adapter package.

Adapters make Cruncher a powerful tool for querying and analyzing data from many different sources, all with a consistent query experience.