Skip to main content

​
Events

Events are discrete occurrences that happen in your application. Unlike metrics which track values over time, events capture individual moments with rich context.

​
Event Structure

Every event has:
FieldTypeRequiredDescription
nameStringYesEvent name (e.g., user.signup)
timestampDateTimeNoWhen it occurred (defaults to now)
propertiesHashNoArbitrary data
tagsHashNoIndexed metadata for filtering
user_idStringNoAssociated user
valueNumberNoNumeric value for aggregations

​
Tracking Events

​
Basic Event

BrainzLab::Flux.track("page.viewed")

​
Event with Properties

Properties store arbitrary data with the event: 
BrainzLab::Flux.track("order.placed", {
  properties: {
    product_id: "prod_123",
    product_name: "Widget Pro",
    quantity: 3,
    discount_code: "SAVE20"
  }
})

​
Event with Tags

Tags are indexed for fast filtering and grouping: 
BrainzLab::Flux.track("api.request", {
  tags: {
    endpoint: "/api/users",
    method: "POST",
    status: "success",
    environment: "production"
  }
})

​
Event with Value

Values enable aggregations (sum, avg, etc.): 
BrainzLab::Flux.track("purchase.completed", {
  user_id: user.id,
  value: order.total,
  properties: {
    order_id: order.id,
    items: order.items.count
  }
})

​
Full Event

BrainzLab::Flux.track("subscription.upgraded", {
  timestamp: Time.current,
  user_id: user.id,
  value: plan.price,
  properties: {
    from_plan: old_plan.name,
    to_plan: new_plan.name,
    billing_cycle: "annual"
  },
  tags: {
    plan_type: new_plan.type,
    source: "upsell_modal"
  }
})

​
Naming Conventions

Use dot notation for hierarchical event names: 
# Good
"user.signup"
"user.login"
"order.placed"
"order.shipped"
"payment.succeeded"
"payment.failed"

# Avoid
"userSignup"
"USER_SIGNUP"
"signup"
Group related events with common prefixes for easier filtering and dashboards.

​
Batch Tracking

The SDK automatically batches events for performance. You can also explicitly batch: 
BrainzLab::Flux.batch do
  users.each do |user|
    BrainzLab::Flux.track("user.migrated", user_id: user.id)
  end
end
For immediate sending (use sparingly): 
BrainzLab::Flux.track("critical.event", flush: true)

​
Querying Events

​
In the Dashboard

Filter events by:
  • Time range
  • Event name (exact or pattern)
  • Tags
  • User ID
  • Value range

​
Via API

curl -X GET "https://flux.brainzlab.ai/api/v1/events" \
  -H "Authorization: Bearer $API_KEY" \
  -d "name=user.signup" \
  -d "from=2024-01-01" \
  -d "to=2024-01-31" \
  -d "tags[plan]=pro"

​
Via MCP

flux_query({
  name: "user.signup",
  from: "2024-01-01",
  tags: { plan: "pro" }
})

​
Event Aggregations

Aggregate events for insights:

​
Count

# Total signups this month
GET /api/v1/events/count?name=user.signup&period=month

​
Stats

# Order value statistics
GET /api/v1/events/stats?name=order.placed&field=value
# Returns: { count: 1234, sum: 98765, avg: 80.03, min: 10, max: 500 }

​
Group By

# Signups by plan
GET /api/v1/events/count?name=user.signup&group_by=tags.plan
# Returns: { pro: 234, starter: 567, enterprise: 89 }

​
Use Cases

​
Funnel Analysis

Track conversion funnel steps: 
BrainzLab::Flux.track("funnel.landing_page", user_id: visitor_id)
BrainzLab::Flux.track("funnel.signup_started", user_id: visitor_id)
BrainzLab::Flux.track("funnel.signup_completed", user_id: user.id)
BrainzLab::Flux.track("funnel.first_action", user_id: user.id)

​
Feature Usage

Track feature adoption: 
BrainzLab::Flux.track("feature.used", {
  user_id: user.id,
  properties: { feature: "export_pdf" },
  tags: { plan: user.plan.name }
})

​
Business Events

Track business-critical moments: 
BrainzLab::Flux.track("revenue.recognized", {
  value: invoice.amount,
  properties: {
    invoice_id: invoice.id,
    customer_id: invoice.customer_id,
    product: invoice.product.name
  },
  tags: {
    currency: invoice.currency,
    region: customer.region
  }
})

​
Best Practices

Use Tags for Filtering

Put filterable dimensions in tags, not properties

Include Value

Add a value for events you’ll aggregate

Consistent Naming

Use dot notation and consistent prefixes

Link Users

Include user_id when available