ElasticAPM Decorators for TypeScript

Supercharge your TypeScript methods with effortless performance monitoring and distributed tracing using Elastic APM!

✨ Features

• Zero-boilerplate: Just decorate your methods—no manual instrumentation needed.
• Automatic Span & Transaction Management: Instantly track performance and errors for any async method.
• TypeScript-first: Built for modern TypeScript projects, with full type safety.
• Flexible: Works with any Elastic APM Node.js agent (v4+).

📦 Installation

npm install elastic-apm-node elasticapm-decorators

Requires: elastic-apm-node v4 or higher (see your package.json for compatibility)

⚡️ Quick Start

1. Import and Configure Elastic APM

import apm from 'elastic-apm-node';
apm.start({
  serviceName: 'my-service',
  // ...other config
});

2. Decorate Your Methods

import { ElasticTransaction, ElasticSpan } from 'elasticapm-decorators';

class UserService {
  @ElasticTransaction('user-signup', 'request')
  async signupUser(data: UserData) {
    // ...your logic
  }

  @ElasticSpan('db-query', 'db', 'postgres')
  async fetchUser(id: string) {
    // ...your logic
  }
}

How It Works

• @ElasticTransaction: Wraps your async method in an Elastic APM transaction. Tracks duration, errors, and outcome.
• @ElasticSpan: Wraps your async method in a span. Perfect for sub-operations (e.g., DB queries, external calls).
• Automatic error handling: Errors are captured and labeled in APM.

Testing

This package is fully tested with Vitest. To run tests:

npm test

API Reference

@ElasticTransaction(name: string, type: string)

• name: Transaction name (e.g., 'user-signup')
• type: Transaction type (e.g., 'request', 'background')

@ElasticSpan(name: string, type: string, subtype?: string)

• name: Span name (e.g., 'db-query')
• type: Span type (e.g., 'db', 'external')
• subtype: (Optional) Span subtype (e.g., 'postgres', 'http')

Why Use This?

• Save time: No more manual APM boilerplate.
• Consistency: Every method is traced the same way.
• Observability: Instantly see performance bottlenecks and errors in Elastic APM.

Contributing

Pull requests, issues, and stars are always welcome! For major changes, please open an issue first to discuss what you would like to change.