Skip to main content

Usage statistics & metrics

@ops-ai/nuxt-toggly-server can optionally batch and send:

  • usage statistics (feature checks + usage / views)
  • metrics (measurements / counters / observations)
RuntimeTransport
Node / Nitro node-serverOptional gRPC (@grpc/grpc-js + @grpc/proto-loader)
Nitro edge / Workers-likeHTTPS JSON to api/usage/stats and api/metrics — no Node gRPC (telemetryTransport: 'https', auto when isEdgeRuntime())

Both use metricsBaseUrl (default https://app.toggly.io/) for the telemetry gateway. That host is separate from definitions (baseUri / https://definitions.toggly.io).

With an appKey, usage and metrics default on. Opt out with config flags or TOGGLY_DISABLE_TELEMETRY=1 (authoritative — wins over explicit true).

Browser companion​

@ops-ai/nuxt-toggly-client 1.3.0 adds a separate compact browser reporter. It defaults to https://metrics.toggly.io and does not use or replace the trusted Nitro gateway described on this page.

Install @ops-ai/nuxt-toggly-client 1.3.0 with Core 1.13.0 or newer. The module @ops-ai/nuxt-toggly 1.3.0 also forwards the browser options. Earlier module versions do not forward all these options.

import { createToggly } from '@ops-ai/nuxt-toggly-client'

const toggly = createToggly({
  appKey: 'your-app-key',
  metricsBaseUrl: 'https://metrics.toggly.io',
})

try {
  await toggly.init()

  toggly.telemetry.recordUsage('checkout', 'blue')
  // Record the view after the application presents the checkout screen.
  toggly.telemetry.recordView('checkout')
  toggly.telemetry.incrementCounter('completed-orders')
  toggly.telemetry.setGauge('cart-items', 3)
  await toggly.telemetry.flushTelemetry()
} finally {
  toggly.client.destroy()
}

Browser configuration accepts enableTelemetry, enableUsageTracking, enableMetrics, metricsBaseUrl, and telemetryFlushIntervalMs. Replacing the client releases the old browser owner. A standalone createToggly owner must be initialized before telemetry calls and destroyed when its lifetime ends. SSR, hydration projection, refresh projection, and keyless clients stay silent. Legacy browser recordUsage(feature, identity?, variant?) and recordView preserve identity as the second argument and forward only the third as the variant. Legacy browser measure and observe are diagnostic no-ops; migrate only values that naturally fit the compact counter or latest-value gauge. See the frontend telemetry contract.

Session identity​

Pass instanceId to createToggly or the module browser configuration. On the initialized standalone owner, await toggly.client.setContext({ identity: 'user-123', instanceId: 'minted-token' }). For logout, explicitly send { identity: '', instanceId: '', groups: [], claims: {} }. The Core client exposes the context update; do not invent a setContext method on the Nuxt composable. See session attribution.

Optional gRPC peers (Node / Nitro)​

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

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

Without those packages, the server still evaluates flags. If usage/metrics are enabled, it logs a warning and skips sending.

Enable / configure​

The Nuxt module (@ops-ai/nuxt-toggly) initializes the server client with your appKey, so usage/metrics default on. For explicit telemetry options (flush intervals, metricsBaseUrl, HTTPS transport), call initServerToggly from @ops-ai/nuxt-toggly-server (for example in a Nitro plugin):

server/plugins/toggly.ts
import { initServerToggly } from '@ops-ai/nuxt-toggly-server'

export default defineNitroPlugin(async () => {
  await initServerToggly({
    appKey: process.env.TOGGLY_APP_KEY!,
    environment: 'Production',
    // Defaults: enableUsageTracking / enableMetrics true when appKey is set
    enableUsageTracking: true,
    enableMetrics: true,
    metricsBaseUrl: 'https://app.toggly.io/',
    usageFlushInterval: 60_000,   // ms; 0 disables the timer
    metricsFlushInterval: 60_000,
    // Node default: 'grpc'. Nitro edge auto-selects 'https'.
    // telemetryTransport: 'https',
    // telemetryAttachProcessHandlers: false, // recommended with HTTPS / edge
  })
})
OptionDefaultNotes
enableUsageTrackingtrue when appKey is setFeature check auto-record + recordServerUsage / recordServerView
enableMetricstrue when appKey is setmeasureServerMetric / incrementServerCounter / observeServerMetric
metricsBaseUrlhttps://app.toggly.io/gRPC / HTTPS gateway (not definitions)
usageFlushInterval / metricsFlushInterval60000Periodic flush; 0 disables timers
telemetryTransportgrpc on Node; https when edge is detectedOverride with 'https' for Nitro edge / Workers-like
telemetryAttachProcessHandlerstrue for gRPC; false for HTTPSProcess signal flush on Node
instanceName / appVersionoptionalReported on payloads

Process signal handlers flush on shutdown when gRPC telemetry is active.

Record usage and metrics​

Feature evaluations via isServerFeatureOn / the shared server client auto-record checks when usage tracking is on. For explicit “used” / “viewed” events and business metrics:

import {
  recordServerUsage,
  recordServerView,
  measureServerMetric,
  incrementServerCounter,
  observeServerMetric,
  flushServerTelemetry,
  closeServerToggly,
} from '@ops-ai/nuxt-toggly-server'

// After a meaningful interaction (e.g. checkout completed in an API route)
recordServerUsage('CheckoutV2', userId)
recordServerView('PricingTable', userId)

measureServerMetric('checkout.latency_ms', 12.3, { feature: 'CheckoutV2' })
incrementServerCounter('checkout.clicks', 1, { feature: 'CheckoutV2' })
observeServerMetric('cart.items', cartSize, { feature: 'CheckoutV2' })

await flushServerTelemetry()
// On process shutdown:
await closeServerToggly()

You can also call recordUsage / recordView / measure / incrementCounter / observe / flushTelemetry on the client from useServerToggly() / getServerToggly().

Nitro edge (HTTPS)​

Nitro edge and Workers-like runtimes cannot open Node gRPC sockets. Set telemetryTransport: 'https' (or rely on auto-detection via isEdgeRuntime()). The server posts JSON to:

  • {metricsBaseUrl}api/usage/stats
  • {metricsBaseUrl}api/metrics

Process signal handlers are disabled on the HTTPS path (telemetryAttachProcessHandlers: false). Flush before the isolate exits:

await flushServerTelemetry()
// or:
await useServerToggly().flushTelemetry()

Same pattern as the standalone Cloudflare Workers integration: HTTPS telemetry, never block flag evaluation on a hard send failure.

Kill switch​

TOGGLY_DISABLE_TELEMETRY=1

This env flag disables usage and metrics even when enableUsageTracking / enableMetrics are explicitly true. Useful in local/CI without changing app config.

See also​