Altitude Metrics SDK

A TypeScript/JavaScript client SDK for collecting and exporting custom metrics on the Altitude platform.

Overview

The Altitude Metrics SDK provides a simple interface for creating and managing three types of metrics:

• Counters: Track cumulative values that only increase
• Histograms: Record observations and distributions
• Gauges: Track values that can go up or down with configurable aggregation

Installation

npm install @thg-altitude/altitude-metrics

Quick Start

import { AltitudeMetrics } from '@thg-altitude/altitude-metrics';

// Initialize the metrics client with your application name
const metrics = new AltitudeMetrics('my-application');

// Create metrics
const requestCounter = metrics.createCounter('http_requests_total');
const responseTimeHistogram = metrics.createHistogram('http_response_time_ms');
const activeConnectionsGauge = metrics.createGauge('active_connections', 'LATEST');

// Record metric values
requestCounter.inc(); // Increment by 1
requestCounter.inc(5); // Increment by 5

responseTimeHistogram.observe(250);
responseTimeHistogram.observe(180);

activeConnectionsGauge.set(42);
activeConnectionsGauge.set(38);

// Export all metrics
metrics.exportMetrics();

API Reference

AltitudeMetrics

The main class for managing metrics.

Constructor

new AltitudeMetrics(applicationName: string)

• applicationName: A string identifier for your application

Methods

createCounter(name: string): Counter

Creates a counter metric that tracks cumulative values.

const counter = metrics.createCounter('api_calls_total');

createHistogram(name: string): Histogram

Creates a histogram metric for recording observations.

const histogram = metrics.createHistogram('request_duration_ms');

createGauge(name: string, aggregation: GaugeAggregation): Gauge

Creates a gauge metric with the specified aggregation method.

const gauge = metrics.createGauge('memory_usage_bytes', 'AVG');

Aggregation options:

• "SUM": Sum all recorded values
• "AVG": Average of all recorded values
• "MEDIAN": Median of all recorded values
• "LATEST": Most recently recorded value

exportMetrics(): MetricExportResult

Exports all metrics as JSON logs to stdout and returns the export result.

const result = metrics.exportMetrics();
if (result.status === "SUCCESS") {
    console.log("Metrics exported successfully");
} else {
    console.error("Export failed:", result.reason);
}

Counter

Methods

inc(amount?: number): void

Increments the counter by the specified amount (defaults to 1).

counter.inc();    // +1
counter.inc(10);  // +10

Histogram

Methods

observe(observation: number): void

Records an observation value.

histogram.observe(42.5);
histogram.observe(100);

Gauge

Methods

set(amount: number): void

Sets a new value for the gauge.

gauge.set(75);
gauge.set(80);

Usage Examples

Web Server Metrics

import { AltitudeMetrics } from '@thg-altitude/altitude-metrics';
import express from 'express';

const app = express();
const metrics = new AltitudeMetrics('web-server');

// Create metrics
const requestsTotal = metrics.createCounter('http_requests_total');
const requestDuration = metrics.createHistogram('http_request_duration_ms');
const activeConnections = metrics.createGauge('http_active_connections', 'LATEST');

// Middleware to track requests
app.use((req, res, next) => {
    const start = Date.now();
    
    requestsTotal.inc();
    
    res.on('finish', () => {
        const duration = Date.now() - start;
        requestDuration.observe(duration);
    });
    
    next();
});

// Export metrics every 30 seconds
setInterval(() => {
    metrics.exportMetrics();
}, 30000);

Database Connection Pool

import { AltitudeMetrics } from '@thg-altitude/altitude-metrics';

const metrics = new AltitudeMetrics('database-service');

const connectionsActive = metrics.createGauge('db_connections_active', 'LATEST');
const connectionsTotal = metrics.createCounter('db_connections_total');
const queryDuration = metrics.createHistogram('db_query_duration_ms');

class DatabasePool {
    private activeConnections = 0;

    async getConnection() {
        this.activeConnections++;
        connectionsActive.set(this.activeConnections);
        connectionsTotal.inc();
        
        // Return connection...
    }

    async executeQuery(query: string) {
        const start = Date.now();
        
        try {
            // Execute query logic...
            const result = await this.runQuery(query);
            return result;
        } finally {
            const duration = Date.now() - start;
            queryDuration.observe(duration);
        }
    }

    releaseConnection() {
        this.activeConnections--;
        connectionsActive.set(this.activeConnections);
    }
}

// Export metrics periodically
setInterval(() => {
    metrics.exportMetrics();
}, 60000);

Batch Processing

import { AltitudeMetrics } from '@thg-altitude/altitude-metrics';

const metrics = new AltitudeMetrics('batch-processor');

const itemsProcessed = metrics.createCounter('items_processed_total');
const processingTime = metrics.createHistogram('item_processing_time_ms');
const queueSize = metrics.createGauge('queue_size', 'LATEST');

async function processBatch(items: any[]) {
    queueSize.set(items.length);
    
    for (const item of items) {
        const start = Date.now();
        
        try {
            await processItem(item);
            itemsProcessed.inc();
        } finally {
            const duration = Date.now() - start;
            processingTime.observe(duration);
        }
    }
    
    queueSize.set(0);
    metrics.exportMetrics();
}

Building

To build the SDK:

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.