🔭 autolemetry

Write once, observe everywhere.

Instrument your Node.js code a single time, keep the DX you love, and stream traces, metrics, logs, and product events to any observability stack without vendor lock-in.

One init(), wrap functions with trace(), and get automatic traces, metrics, and events:

import { init, trace, track } from 'autolemetry';
import { PostHogSubscriber, SlackSubscriber } from 'autolemetry-subscribers';

// Initialize once at startup
init({
  service: 'checkout-api',
  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT, // Grafana, Datadog, Tempo, etc.
  subscribers: [
    new PostHogSubscriber({ apiKey: process.env.POSTHOG_KEY! }),
    new SlackSubscriber({ webhookUrl: process.env.SLACK_WEBHOOK! }),
  ],
});

// Wrap any function - automatic spans, error tracking, and context
export const processOrder = trace(async function processOrder(
  orderId: string,
  amount: number,
) {
  const user = await db.users.findById(orderId);
  const payment = await chargeCard(user.cardId, amount);

  // Product events automatically enriched with trace context
  // Sent to: OTLP + PostHog + Slack (all in one call!)
  track('order.completed', { orderId, amount, userId: user.id });

  return payment;
});

That's it. Every call to processOrder() now:

• ✅ Creates a span with automatic error handling
• ✅ Tracks metrics (duration, success rate)
• ✅ Sends events with traceId and spanId to all adapters
• ✅ Works with any OTLP-compatible backend (Grafana, Datadog, New Relic, Tempo, etc.)

→ See complete examples and API docs

Packages

This monorepo contains the following packages:

autolemetry

Core library providing ergonomic OpenTelemetry instrumentation with:

• Drop-in DX with trace(), span(), and decorators
• Adaptive sampling (10% baseline, 100% errors/slow paths)
• Production hardening (rate limiting, circuit breakers, redaction)
• Auto trace context enrichment
• LLM observability via OpenLLMetry integration
• AI workflow patterns (multi-agent, RAG, evaluation loops)

→ View full documentation

autolemetry-subscribers

Product events subscribers for:

• PostHog
• Mixpanel
• Amplitude
• Slack webhooks
• Custom webhooks

→ View subscribers documentation

autolemetry-edge

Edge runtime support for:

• Cloudflare Workers
• Vercel Edge Functions
• Other edge environments

→ View edge documentation

Migrating from OpenTelemetry?

Migration Guide - Migrate from vanilla OpenTelemetry to autolemetry:

• Quick start with copy-paste code examples
• Pattern-by-pattern transformations (environment variables, manual SDK setup, manual spans, logger integration, sampling)
• Side-by-side before/after comparisons
• 9-phase migration checklist
• Edge cases and when not to migrate

Typical migration: Replace NODE_OPTIONS and 30+ lines of SDK boilerplate with init(), wrap functions with trace() instead of manual span.start()/span.end().

Quick Start

npm install autolemetry
# Optional: Add event subscribers (PostHog, Slack, Mixpanel, etc.)
npm install autolemetry-subscribers
# or
pnpm add autolemetry
pnpm add autolemetry-subscribers  # Optional

Quick Debug Mode

See traces instantly during development - perfect for progressive development:

import { init, trace } from 'autolemetry';

// Start with console-only (no backend needed)
init({
  service: 'my-app',
  debug: true  // Outputs spans to console
});

// Your traced functions work as normal
const result = await trace(async () => {
  // Your code here
  return 'success';
})();

// Span printed to console automatically!

How it works:

• debug: true - Print spans to console AND send to backend (if endpoint configured)
  • No endpoint = console-only (perfect for local development)
  • With endpoint = console + backend (verify before choosing provider)
• No debug flag - Send to backend only (default production behavior)

Or use environment variable:

AUTOLEMETRY_DEBUG=true node server.js

Environment Variables

Configure autolemetry using standard OpenTelemetry environment variables:

export OTEL_SERVICE_NAME=my-app
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=YOUR_API_KEY
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production

Then call init() without any config - it picks up env vars automatically:

init({ service: 'my-app' }); // Minimal config, env vars fill the rest

→ See complete environment variable documentation

→ Full API documentation

Development

Prerequisites

• Node.js 18+
• pnpm 8+

Setup

# Clone and install dependencies
git clone https://github.com/jagreehal/autolemetry.git
cd autolemetry
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run example apps
pnpm --filter @jagreehal/example-basic start
pnpm --filter @jagreehal/example-http start

Project Structure

autolemetry/
├── packages/
│   ├── autolemetry/          # Core library
│   ├── autolemetry-subscribers/ # Event subscribers
│   └── autolemetry-edge/     # Edge runtime support
├── apps/
│   ├── example-basic/        # Basic usage example
│   ├── example-http/         # Express server example
│   └── cloudflare-example/   # Cloudflare Workers example
└── turbo.json                # Turborepo configuration

Available Scripts

# Development
pnpm dev              # Watch mode for all packages
pnpm build            # Build all packages
pnpm test             # Run all tests
pnpm test:integration # Run integration tests

# Code quality
pnpm lint             # Lint all packages
pnpm format           # Format code with Prettier
pnpm type-check       # TypeScript type checking

# Releases
pnpm changeset        # Create a changeset
pnpm version-packages # Version packages
pnpm release          # Publish to npm

Running Examples

Basic Example

pnpm --filter @jagreehal/example-basic start

HTTP Server Example

pnpm --filter @jagreehal/example-http start

Cloudflare Workers Example

pnpm --filter cloudflare-example dev

Contributing

We welcome contributions! Please see our contributing guidelines for details.

Development Workflow

1. Fork and clone the repository
2. Create a branch for your feature: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Run tests: pnpm test
5. Create a changeset: pnpm changeset
6. Commit your changes: git commit -am "Add new feature"
7. Push to your fork: git push origin feature/my-feature
8. Open a pull request

Adding a Changeset

We use changesets for version management:

pnpm changeset

Follow the prompts to:

1. Select which packages changed
2. Choose semver bump (major/minor/patch)
3. Write a summary of your changes

Architecture

Autolemetry is built on top of OpenTelemetry and provides:

• Ergonomic API layer - Wraps verbose OpenTelemetry APIs
• Smart defaults - Production-ready configuration out of the box
• Platform agnostic - Works with any OTLP-compatible backend
• Type-safe - Full TypeScript support with strict types
• Modular design - Use only what you need

Why Autolemetry?

Challenge	With autolemetry
Raw OpenTelemetry is verbose	One-line trace() wrapper with automatic lifecycle
Vendor SDKs create lock-in	OTLP-native, works with any backend
Need both observability & events	Unified API for traces, metrics, logs, and events
Production safety concerns	Built-in sampling, rate limiting, redaction

Troubleshooting

Having issues seeing your traces? Use ConsoleSpanExporter for visual debugging or InMemorySpanExporter for testing. See the full troubleshooting guide in the detailed docs.

Roadmap

• Core tracing API
• Metrics support
• Log correlation
• Product events subscribers
• Edge runtime support
• LLM observability (OpenLLMetry)

Community & Support

• Report bugs
• Request features
• Join discussions

License

MIT - See LICENSE for details.