TrueMark Lambda Otel Library

This library provides common helper functions for otel implementation.

Versioning

This project follows a semantic versioning pattern.

<major>.<minor>.<patch>

Library usage

At the top of your handler file, register OTel and then pull meter/tracer helpers as needed.

// src/handler.ts
import 'truemark-aws-lambda-otel/helpers/register-otel';
import {otelMeter, otelTracer} from 'truemark-aws-lambda-otel/helpers';

Instrumentation

This library supports instrumentation for various AWS and Node.js services. To keep your Lambda bundle size minimal, most instrumentations are opt-in via environment variables and peer dependencies.

Default Instrumentations

By default (when OTEL_INSTRUMENTATIONS is not set), the following instrumentations are enabled:

• aws-sdk - AWS SDK v3 (DynamoDB, S3, SQS, etc.)
• http - Node.js built-in HTTP/HTTPS modules
• fetch - Node.js Fetch API

These are included as direct dependencies and require no additional installation.

Enabling Additional Instrumentations

Set the OTEL_INSTRUMENTATIONS environment variable with a comma-separated list to customize which instrumentations to enable:

# Override defaults and enable specific instrumentations
OTEL_INSTRUMENTATIONS=aws-sdk,http,undici

# Disable all instrumentations (empty or set to "none")
OTEL_INSTRUMENTATIONS=

Available Instrumentations

| Name | Package | Use Case | Installation Required | | --------------------- | ----------------------------------------- | --------------------------------------- | ------------------------------------------------- | | aws-sdk (default) | @opentelemetry/instrumentation-aws-sdk | AWS SDK v3 (DynamoDB, S3, etc.) | Included | | http (default) | @opentelemetry/instrumentation-http | Node.js built-in http/https modules | Included | | fetch (default) | @opentelemetry/instrumentation-fetch | Node.js Fetch API | Included | | undici | @opentelemetry/instrumentation-undici | Undici HTTP client | @opentelemetry/instrumentation-undici@^0.17.0 | | pg | @opentelemetry/instrumentation-pg | PostgreSQL client | @opentelemetry/instrumentation-pg@^0.59.0 | | mysql | @opentelemetry/instrumentation-mysql | MySQL client | @opentelemetry/instrumentation-mysql@^0.52.0 | | mysql2 | @opentelemetry/instrumentation-mysql2 | MySQL2 client | @opentelemetry/instrumentation-mysql2@^0.53.0 | | oracle / oracledb | @opentelemetry/instrumentation-oracledb | Oracle Database client | @opentelemetry/instrumentation-oracledb@^0.32.0 | | redis | @opentelemetry/instrumentation-redis | Redis client | @opentelemetry/instrumentation-redis@^0.55.0 | | ioredis | @opentelemetry/instrumentation-ioredis | IORedis client | @opentelemetry/instrumentation-ioredis@^0.54.0 | | express | @opentelemetry/instrumentation-express | Express.js framework | @opentelemetry/instrumentation-express@^0.55.0 | | dns | @opentelemetry/instrumentation-dns | Node.js DNS module | @opentelemetry/instrumentation-dns@^0.50.0 | | net | @opentelemetry/instrumentation-net | Node.js Net module | @opentelemetry/instrumentation-net@^0.50.0 |

Installing Additional Instrumentations

Install only the instrumentation packages you need (beyond the defaults aws-sdk, http, and fetch):

# Example: Install PostgreSQL and MySQL2 instrumentation
pnpm add @opentelemetry/instrumentation-pg @opentelemetry/instrumentation-mysql2

# Or with npm
npm install @opentelemetry/instrumentation-pg @opentelemetry/instrumentation-mysql2

Lambda Configuration Examples

Using Environment Variables Directly

# Example 1: Use defaults (aws-sdk + http + fetch)
# No OTEL_INSTRUMENTATIONS variable needed
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otlp-endpoint.com
OTEL_SERVICE_NAME=my-lambda-service

# Example 2: Add database instrumentation
OTEL_INSTRUMENTATIONS=aws-sdk,http,fetch,pg,mysql2
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otlp-endpoint.com
OTEL_SERVICE_NAME=my-lambda-service

# Example 3: Disable all instrumentations
OTEL_INSTRUMENTATIONS=
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otlp-endpoint.com
OTEL_SERVICE_NAME=my-lambda-service

Recommendations for Lambda

For most Lambda functions:

• Default (aws-sdk + http + fetch) - Good baseline for most functions
• + Database:
  • PostgreSQL: Add pg
  • MySQL: Add mysql2 (more common than mysql)
  • Oracle: Add oracle or oracledb
  • Redis/ElastiCache: Add ioredis (more common than redis)
• Alternative HTTP clients: Replace http with undici if using undici
• Avoid: dns, net unless debugging network issues (adds overhead)