crystal-loki-client

Crystal client library for accessing Grafana Loki APIs.

Supported APIs

Query endpoints

• /loki/api/v1/query — instant query
• /loki/api/v1/query_range — range query
• /loki/api/v1/labels — list label names
• /loki/api/v1/label/<name>/values — list label values
• /loki/api/v1/series — query streams (GET + POST form-encoded)
• /loki/api/v1/index/stats — index statistics
• /loki/api/v1/index/volume — log volume
• /loki/api/v1/index/volume_range — log volume over time
• /loki/api/v1/patterns — pattern detection
• /loki/api/v1/detected_fields — detected fields (GET + POST form-encoded)
• /loki/api/v1/detected_field/<name>/values — detected field values (GET + POST form-encoded)
• /loki/api/v1/format_query — format/validate LogQL
• /loki/api/v1/tail — tail logs via WebSocket
• /loki/api/v1/status/buildinfo — build information

Status/health endpoints

• /ready — readiness probe
• /metrics — Prometheus metrics
• /config — current configuration (?mode=diffs / ?mode=defaults)
• /services — list running services
• /log_level — current log level

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     loki-client:
       github: spider-gazelle/crystal-loki-client

2. Run shards install

Usage

require "loki-client"

You can configure the environment using the following variables or configure them via code.

• LOKI_ADDR - Loki Server address.
• LOKI_USERNAME - Username for HTTP basic auth.
• LOKI_PASSWORD - Password for HTTP basic auth.
• LOKI_CA_CERT_PATH - Path to the server Certificate Authority.
• LOKI_TLS_SKIP_VERIFY - Server certificate TLS skip verify.
• LOKI_CLIENT_CERT_PATH - Path to the client certificate.
• LOKI_CLIENT_KEY_PATH - Path to the client certificate key.
• LOKI_ORG_ID - adds X-Scope-OrgID to API requests for representing tenant ID. Useful for requesting tenant data when bypassing an auth gateway.
• LOKI_QUERY_TAGS - adds X-Query-Tags http header to API requests. Useful for tracking the query.
• LOKI_BEARER_TOKEN - adds the Authorization header to API requests for authentication purposes.
• LOKI_BEARER_TOKEN_FILE - adds the Authorization header to API requests for authentication purposes.
• LOKI_AUTH_HEADER - The authorization header used. Defaults to Authorization
• https_proxy or http_proxy - for proxy configuration

Examples

client = Loki::Client.from_env

# Query endpoints
response = client.query(query: "{job=\"varlogs\"}")
response = client.query_range(query: "{job=\"varlogs\"}", start: 1.hour.ago, end_time: Time.local)
labels = client.list_labels
values = client.list_label_values("job")
series = client.series(matches: ["{app=\"loki\"}"])
stats = client.stats(query: "{job=\"foo\"}")
volume = client.volume(query: "{job=\"foo\"}", start: 1.hour.ago, end_time: Time.local)
patterns = client.patterns(query: "{app=\"loki\"}", start: 1.hour.ago, end_time: Time.local)
fields = client.detected_fields(query: "{app=\"myapp\"}", start: 1.hour.ago, end_time: Time.local)
formatted = client.format_query("{foo= \"bar\"}")
info = client.buildinfo

# Tail via WebSocket
ws = client.tail(query: "{job=\"varlogs\"}")
client.tail(query: "{job=\"varlogs\"}") { |msg| pp msg }

# Status/health endpoints
ready = client.ready?
prometheus_text = client.metrics
config = client.get_config
config_diffs = client.get_config(mode: "diffs")
services = client.services
level = client.log_level

Development

Contributing

1. Fork it (https://github.com/spider-gazelle/crystal-loki-client/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Ali Naqvi - creator and maintainer