Skip to main content

Usage statistics & metrics

@ops-ai/toggly-node-core can optionally batch and send:

  • usage statistics (feature checks + usage / views)
  • metrics (measurements / counters / observations)

Transport is gRPC to metricsBaseUrl (default https://app.toggly.io/). That host is separate from definitions (baseUrl / https://definitions.toggly.io).

Install optional peers when you want telemetry to leave the process:

npm install @grpc/grpc-js @grpc/proto-loader

Without those packages, flag evaluation still works. If usage/metrics are enabled, the SDK warns and skips sending.

Enable / configure​

With an appKey, usage and metrics default on. Set the flags to false, or leave them unset and export TOGGLY_DISABLE_TELEMETRY=1, to opt out.

import { createTogglyClient } from '@ops-ai/toggly-node-core'

const client = createTogglyClient({
  appKey: process.env.TOGGLY_APP_KEY!,
  environment: 'Production',
  // Defaults: true when appKey is set (unless TOGGLY_DISABLE_TELEMETRY=1)
  enableUsageTracking: true,
  enableMetrics: true,
  metricsBaseUrl: 'https://app.toggly.io/',
  usageFlushInterval: 60_000,   // ms; 0 disables the timer
  metricsFlushInterval: 60_000,
  instanceName: 'api-1',        // optional
  appVersion: '1.2.3',          // optional
})
await client.init()
OptionDefaultNotes
enableUsageTrackingtrue when appKey is setAuto-records checks; recordUsage / recordView
enableMetricstrue when appKey is setmeasure / incrementCounter / observe
metricsBaseUrlhttps://app.toggly.io/gRPC gateway (not definitions)
usageFlushInterval / metricsFlushInterval60000Periodic flush; 0 disables timers
instanceName / appVersionoptionalReported on payloads

Record usage​

Feature checks are recorded automatically when usage tracking is enabled.

For explicit “used” / “viewed” events:

client.recordUsage('MyFeature', 'user-123')
client.recordView('PricingTable', 'user-123')

Emit metrics​

client.measure('checkout.latency_ms', 12.3, { feature: 'CheckoutV2' })
client.incrementCounter('checkout.clicks', 1, { feature: 'CheckoutV2' })
client.observe('cart.items', 4, { feature: 'CheckoutV2' })

Flushing and shutdown​

Batches flush on the configured intervals. Flush manually or on process exit:

await client.flushTelemetry()
await client.close() // stops timers, flushes, releases resources

Kill switch​

TOGGLY_DISABLE_TELEMETRY=1

When enableUsageTracking / enableMetrics are unset, this env flag turns the defaults off (useful in unit tests and CI). Prefer explicit enableUsageTracking: false / enableMetrics: false in application config when you always want telemetry off.

See also​