autotel
Version:
Write Once, Observe Anywhere
241 lines (237 loc) • 7.42 kB
text/typescript
import { Logger } from './logger.cjs';
import { EventAttributes, FunnelStatus, OutcomeStatus } from './event-subscriber.cjs';
import { MetricsCollector } from './metric-testing.cjs';
import 'pino';
/**
* Metrics API for OpenTelemetry
*
* Track business metrics for OpenTelemetry (Prometheus/Grafana).
* For business people who think in metrics.
*
* @example Track business metrics
* ```typescript
* const metrics = new Metric('checkout')
*
* // Track events as metrics
* metrics.trackEvent('order.completed', {
* amount: 99.99,
* currency: 'USD'
* })
*
* // Track conversion funnels
* metrics.trackFunnelStep('checkout', 'started', { cartValue: 99.99 })
* metrics.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 })
*
* // Track outcomes
* metrics.trackOutcome('payment.process', 'success', { amount: 99.99 })
* metrics.trackOutcome('payment.process', 'failure', { error: 'insufficient_funds' })
*
* // Track values
* metrics.trackValue('revenue', 149.99, { currency: 'USD' })
* ```
*/
/**
* Metrics class for tracking business metrics in OpenTelemetry
*
* Track critical business indicators such as:
* - User events (signups, purchases, feature usage) as metrics
* - Conversion funnels (signup → activation → purchase)
* - Business outcomes (success/failure rates)
* - Value metrics (revenue, counts, etc.)
*
* All metrics are sent to OpenTelemetry (OTLP/Prometheus/Grafana).
*/
/**
* Metric configuration for customizing metric names and descriptions
*/
interface MetricConfig {
/** Metric name (e.g., 'metrics.events' or 'custom.events') */
name?: string;
/** Metric description */
description?: string;
/** Metric unit (default: '1') */
unit?: string;
}
/**
* Metrics options
*/
interface MetricsOptions {
/** Optional logger for audit trail */
logger?: Logger;
/** Optional collector for testing (captures metrics in memory) */
collector?: MetricsCollector;
/**
* Namespace for metrics (default: 'metrics')
* Results in metrics like: {serviceName}.{namespace}.events
*/
namespace?: string;
/**
* Custom metric configurations
* Override metric names, descriptions, and units
*/
metrics?: {
events?: MetricConfig;
funnel?: MetricConfig;
outcomes?: MetricConfig;
value?: MetricConfig;
};
}
declare class Metric {
private serviceName;
private eventCounter;
private funnelCounter;
private outcomeCounter;
private valueHistogram;
private logger?;
private collector?;
/**
* Create a new Metrics instance
*
* @param serviceName - Service name for metric namespacing
* @param options - Optional configuration (logger, collector, namespace, metrics)
*
* @example Basic usage (default 'metrics' namespace)
* ```typescript
* const metrics = new Metric('checkout');
* // Creates: checkout.metrics.events, checkout.metrics.funnel, etc.
* ```
*
* @example Custom namespace
* ```typescript
* const metrics = new Metric('api', { namespace: 'business' });
* // Creates: api.business.events, api.business.funnel, etc.
* ```
*
* @example Custom metric names and descriptions
* ```typescript
* const metrics = new Metric('payments', {
* metrics: {
* outcomes: {
* name: 'payments.transactions',
* description: 'Payment transaction outcomes',
* unit: 'transactions'
* },
* value: {
* name: 'payments.revenue',
* description: 'Payment revenue in USD',
* unit: 'USD'
* }
* }
* });
* ```
*/
constructor(serviceName: string, options?: MetricsOptions);
/**
* Track a business event as a metric
*
* Use this for tracking user actions, business events, product usage as metrics:
* - "user.signup"
* - "order.completed"
* - "feature.used"
*
* @example
* ```typescript
* // Track user signup as metric
* metrics.trackEvent('user.signup', {
* userId: '123',
* plan: 'pro'
* })
*
* // Track order as metric
* metrics.trackEvent('order.completed', {
* orderId: 'ord_123',
* amount: 99.99
* })
* ```
*/
trackEvent(eventName: string, attributes?: EventAttributes): void;
/**
* Track conversion funnel steps as metrics
*
* Monitor where users drop off in multi-step processes.
*
* @example
* ```typescript
* // Track signup funnel
* metrics.trackFunnelStep('signup', 'started', { userId: '123' })
* metrics.trackFunnelStep('signup', 'email_verified', { userId: '123' })
* metrics.trackFunnelStep('signup', 'completed', { userId: '123' })
*
* // Track checkout flow
* metrics.trackFunnelStep('checkout', 'started', { cartValue: 99.99 })
* metrics.trackFunnelStep('checkout', 'payment_info', { cartValue: 99.99 })
* metrics.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 })
* ```
*/
trackFunnelStep(funnelName: string, status: FunnelStatus, attributes?: EventAttributes): void;
/**
* Track outcomes (success/failure/partial) as metrics
*
* Monitor success rates of critical operations.
*
* @example
* ```typescript
* // Track email delivery
* metrics.trackOutcome('email.delivery', 'success', {
* recipientType: 'user',
* emailType: 'welcome'
* })
*
* metrics.trackOutcome('email.delivery', 'failure', {
* recipientType: 'user',
* errorCode: 'invalid_email'
* })
*
* // Track payment processing
* metrics.trackOutcome('payment.process', 'success', { amount: 99.99 })
* metrics.trackOutcome('payment.process', 'failure', { error: 'insufficient_funds' })
* ```
*/
trackOutcome(operationName: string, status: OutcomeStatus, attributes?: EventAttributes): void;
/**
* Track value metrics
*
* Record numerical values like revenue, transaction amounts,
* item counts, processing times, engagement scores, etc.
*
* @example
* ```typescript
* // Track revenue
* metrics.trackValue('order.revenue', 149.99, {
* currency: 'USD',
* productCategory: 'electronics'
* })
*
* // Track items per cart
* metrics.trackValue('cart.item_count', 5, {
* userId: '123'
* })
*
* // Track processing time
* metrics.trackValue('api.response_time', 250, {
* unit: 'ms',
* endpoint: '/api/checkout'
* })
* ```
*/
trackValue(metricName: string, value: number, attributes?: EventAttributes): void;
}
/**
* Get or create a Metrics instance for a service
*
* @param serviceName - Service name for metric namespacing
* @param logger - Optional logger
* @returns Metrics instance
*
* @example
* ```typescript
* const metrics = getMetrics('checkout')
* metrics.trackEvent('order.completed', { orderId: '123' })
* ```
*/
declare function getMetrics(serviceName: string, logger?: Logger): Metric;
/**
* Reset all metrics instances (mainly for testing)
*/
declare function resetMetrics(): void;
export { EventAttributes, FunnelStatus, Metric, type MetricConfig, type MetricsOptions, OutcomeStatus, getMetrics, resetMetrics };