lex-metering

Captures LLM token usage, latency, and routing metrics per task for cost attribution and intelligent routing decisions.

Ruby >= 3.4 | License: MIT | Author: @Esity

Purpose

lex-metering records every LLM call made through a Legion digital worker: tokens consumed (input, output, thinking), latency, wall-clock time, CPU time, external API calls, and routing reason. Data is persisted to the metering_records table and queried for cost attribution and routing statistics.

Installation

Included with the LegionIO framework. No separate installation needed.

Usage

# Record an LLM call
Legion::Extensions::Metering::Runners::Metering.record(
  worker_id: 'my-worker',
  task_id:   42,
  provider:  'anthropic',
  model_id:  'claude-opus-4-6',
  input_tokens:  1000,
  output_tokens: 500,
  latency_ms:    1200,
  routing_reason: 'cost_optimization'
)

# Query worker costs
costs = Legion::Extensions::Metering::Runners::Metering.worker_costs(
  worker_id: 'my-worker',
  period:    'daily'
)

# Query routing statistics
stats = Legion::Extensions::Metering::Runners::Metering.routing_stats

Database

Requires legion-data. Creates the metering_records table via Sequel migration. Extension loads without legion-data (data_required? false) — record returns a hash for RMQ publishing; query methods require Legion::Data to be available.

Record Retention

Metering records are pruned automatically by the Cleanup actor, which runs once per day. The default retention period is 90 days. Records with a recorded_at older than the cutoff are permanently deleted.

To trigger cleanup manually:

Legion::Extensions::Metering::Runners::Metering.cleanup_old_records(retention_days: 90)
# => { purged: 1234, retention_days: 90, cutoff: 2025-12-15 00:00:00 UTC }

Query Methods

Method Parameters Period Values
worker_costs worker_id:, period: 'daily' 'daily', 'weekly', 'monthly'
team_costs team:, period: 'daily' 'daily', 'weekly', 'monthly'
routing_stats worker_id: nil —