Skip to main content

​
Metrics

Metrics are numeric values tracked over time. Flux supports four metric types, each designed for different use cases.

​
Metric Types

TypeDescriptionAggregationExample
GaugeCurrent valueLastusers.online, queue.depth
CounterCumulative countSumapi.requests, emails.sent
DistributionStatistical valuesAvg, P50, P95, P99response_time, order_value
SetUnique elementsCount distinctdaily_active_users

​
Gauge

A gauge represents a current value that can go up or down. Only the last value in each time bucket is kept. 
# Current users online
BrainzLab::Flux.gauge("users.online", 234)

# Queue depth
BrainzLab::Flux.gauge("jobs.queue_depth", Sidekiq::Queue.new.size)

# Memory usage
BrainzLab::Flux.gauge("system.memory_mb", get_memory_usage)

# With tags
BrainzLab::Flux.gauge("cache.size", cache.size, tags: {
  cache_name: "sessions",
  region: "us-east-1"
})
Use gauges for:
  • Current counts (online users, queue depth)
  • Resource levels (memory, disk, connections)
  • Configuration values
  • Any point-in-time measurement

​
Counter

A counter tracks cumulative counts. Values are summed within time buckets. 
# Increment by 1
BrainzLab::Flux.increment("api.requests")

# Increment by N
BrainzLab::Flux.increment("emails.sent", 5)

# Alternative syntax
BrainzLab::Flux.counter("api.requests", 1)

# With tags
BrainzLab::Flux.increment("api.requests", tags: {
  endpoint: "/users",
  method: "POST",
  status: 200
})
Use counters for:
  • Request counts
  • Events processed
  • Emails sent
  • Errors occurred
  • Any monotonically increasing value

​
Distribution

A distribution tracks the statistical distribution of values. Flux computes min, max, avg, sum, count, and percentiles. 
# Response time
BrainzLab::Flux.distribution("response_time", 145.2)

# Order value
BrainzLab::Flux.distribution("order.value", order.total)

# File size
BrainzLab::Flux.distribution("upload.size_bytes", file.size)

# With tags
BrainzLab::Flux.distribution("query.duration_ms", query_time, tags: {
  query_type: "search",
  index: "products"
})

​
Timing Helper

Automatically measure execution time: 
BrainzLab::Flux.measure("pdf.generate") do
  generate_pdf(document)
end

# With tags
BrainzLab::Flux.measure("api.external_call", tags: { service: "stripe" }) do
  Stripe::Charge.create(params)
end

# Returns the block's result
result = BrainzLab::Flux.measure("heavy.computation") do
  compute_something_expensive
end
Use distributions for:
  • Response times
  • Query durations
  • File/payload sizes
  • Order values
  • Any value where you need percentiles

​
Distribution Aggregations

When querying distributions, you get:
MetricDescription
countNumber of values
sumTotal of all values
avgAverage value
minMinimum value
maxMaximum value
p50Median (50th percentile)
p9090th percentile
p9595th percentile
p9999th percentile

​
Set

A set tracks unique elements, giving you cardinality (distinct count). 
# Daily active users
BrainzLab::Flux.set("daily_active_users", user.id)

# Unique visitors
BrainzLab::Flux.set("unique_visitors", visitor_id)

# Unique products viewed
BrainzLab::Flux.set("products.viewed", product.id)

# With tags
BrainzLab::Flux.set("active_users", user.id, tags: {
  plan: user.plan.name,
  region: user.region
})
Use sets for:
  • Unique users/visitors
  • Distinct values seen
  • Cardinality tracking

​
Tags

All metric types support tags for segmentation: 
BrainzLab::Flux.increment("api.requests", tags: {
  endpoint: "/api/users",
  method: "POST",
  status: 201,
  version: "v2"
})
Tags allow you to:
  • Filter metrics in dashboards
  • Group by dimensions
  • Create multi-dimensional views

​
Tag Best Practices

Low Cardinality

Use tags with bounded values (status codes, regions, plans)

Avoid High Cardinality

Don’t use user IDs or timestamps as tags

Consistent Keys

Use the same tag keys across related metrics

Meaningful Values

Use human-readable tag values

​
Default Tags

Set global tags applied to all metrics: 
BrainzLab.configure do |config|
  config.flux_default_tags = {
    service: "api",
    environment: Rails.env,
    version: MyApp::VERSION,
    hostname: Socket.gethostname
  }
end

​
Batching

The SDK batches metrics for performance. Configure batch behavior: 
BrainzLab.configure do |config|
  # Send when batch reaches this size
  config.flux_batch_size = 100

  # Or after this interval (seconds)
  config.flux_flush_interval = 10
end
Force immediate send: 
BrainzLab::Flux.gauge("critical.metric", value, flush: true)

​
Querying Metrics

​
Dashboard

View metrics in the Flux dashboard with:
  • Time range selection
  • Aggregation functions
  • Tag filtering
  • Multiple metric overlay

​
API

# Get metric time series
curl -X GET "https://flux.brainzlab.ai/api/v1/metrics/response_time/query" \
  -H "Authorization: Bearer $API_KEY" \
  -d "from=2024-01-01T00:00:00Z" \
  -d "to=2024-01-02T00:00:00Z" \
  -d "aggregation=p95" \
  -d "interval=1h"

​
MCP

flux_metric({
  name: "response_time",
  aggregation: "p95",
  from: "1h ago",
  tags: { endpoint: "/api/users" }
})

​
Use Cases

​
Application Performance

# Track response times
around_action do |controller, action|
  BrainzLab::Flux.measure("request.duration", tags: {
    controller: controller.class.name,
    action: action
  }) { action.call }
end

​
Business Metrics

# Revenue tracking
after_action :track_order, only: :create

def track_order
  BrainzLab::Flux.distribution("order.value", @order.total, tags: {
    currency: @order.currency,
    region: @order.shipping_region
  })
  BrainzLab::Flux.increment("orders.count")
  BrainzLab::Flux.set("customers.active", @order.customer_id)
end

​
Infrastructure Monitoring

# Periodic gauge updates
every 30.seconds do
  BrainzLab::Flux.gauge("sidekiq.queued", Sidekiq::Stats.new.enqueued)
  BrainzLab::Flux.gauge("sidekiq.workers", Sidekiq::Workers.new.size)
  BrainzLab::Flux.gauge("redis.memory_mb", redis.info["used_memory"].to_i / 1_000_000)
end