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 @ops-ai/nuxt-toggly-client does not send this telemetry.

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​