Instrumentation Files Guide

Historical Architecture

SigNoz (ingest.us.signoz.cloud), instrumentation.cjs, pdf_processor_service, and pdf-api / Celery / pdf-worker have been retired. Current Node.js OpenTelemetry bootstrap lives in apps/webapp/otel-init.cjs and packages/observability/src/otel-config.ts (with logging in packages/observability/src/logger.ts and packages/utils/src/logger.ts), while Python worker tracing lives in apps/temporal-worker/ and packages/pdf-shared/. See Observability Overview for the active setup.

Overview

This guide explains the observability instrumentation setup following SigNoz’s TypeScript documentation.

🎯 Primary File

instrumentation.cjs (Single Implementation)

Purpose: JavaScript implementation following SigNoz’s exact documentation pattern
When to use: All environments (development, production, Docker)
How to use:

# For development (assuming you have a CJS-based entrypoint)
node --require ./instrumentation.cjs your-app.js

# For production (in package.json scripts)
"start": "NODE_OPTIONS='--import ./instrumentation.cjs' astro dev"

Features:

• ✅ Follows SigNoz documentation exactly
• ✅ Production-ready and development-friendly
• ✅ Environment variable based configuration
• ✅ Automatic fallback to console export for development
• ✅ Proper resource configuration and graceful shutdown

🔧 Supporting Files

3. src/lib/observability/ Directory

Purpose: Additional observability utilities and helpers

Files:

• astro-integration.ts: Astro middleware for request tracing
• api-instrumentation.ts: Wrapper functions for API routes
• node-metrics.ts: Custom business metrics
• src/utils/logger.ts: Main structured logger with trace correlation

🚀 Usage Patterns

For Production (Recommended)

Use the JavaScript implementation with environment variables:

# Set SigNoz configuration
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.us.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=your-key"
export OTEL_SERVICE_NAME="erp-unlocked-backend"

# Run with tracing (as configured in package.json)
npm start

For Development

Use console export for local testing:

export OTEL_CONSOLE_EXPORT=true
export ENABLE_OBSERVABILITY=true

# Run normally - traces will appear in console
npm run dev

For No-Code Instrumentation

Follow SigNoz’s no-code approach:

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.us.signoz.cloud:443"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="erp-unlocked-backend"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=your-key"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

npm start

🐛 Troubleshooting

TypeScript Compilation

For production deployment:

• Compile TypeScript: npx tsc
• The compiled instrumentation.js will be used in production
• TypeScript provides better development experience and type safety

No Traces Appearing

1. Check environment variables are set correctly
2. Verify SigNoz endpoint and ingestion key
3. Enable console export for debugging: OTEL_CONSOLE_EXPORT=true

Performance Impact

• The instrumentation has minimal performance impact
• Metrics collection is optional and can be disabled
• Console export should only be used in development

📋 Migration Notes

From Legacy Implementation

• src/lib/observability/node-tracer.ts - REMOVED (was redundant)
• src/lib/observability/node-logger.ts - REMOVED (replaced by src/utils/logger.ts)
• tracing.js - REMOVED (redundant with CJS version)
• Single instrumentation.cjs file following SigNoz documentation
• Environment variables updated to SigNoz standards

Environment Variable Changes

• SIGNOZ_OTLP_ENDPOINT → OTEL_EXPORTER_OTLP_ENDPOINT
• SIGNOZ_API_KEY → Include in OTEL_EXPORTER_OTLP_HEADERS
• Added OTEL_TRACES_EXPORTER=otlp
• Added OTEL_NODE_RESOURCE_DETECTORS=env,host,os

📝 Logging Integration

Node.js Logging (src/utils/logger.ts)

Purpose: SigNoz-compatible logging using Pino following SigNoz Pino documentation.

Key Features:

• Pino Transport: Uses pino-opentelemetry-transport for SigNoz integration
• Development Mode: Pretty printing for local development
• Production Mode: JSON structured logs sent to SigNoz
• Trace Correlation: Automatic correlation with OpenTelemetry traces
• Environment Detection: Fallback for browser environments

Usage:

import { logger } from '@/utils/logger';

// Structured logging with metadata
logger.info('Order processed', {
  orderId: '123',
  amount: 99.99,
  customerId: 'cust-456',
});

// Error logging with full context
logger.error('Payment failed', error, {
  orderId: '456',
  paymentMethod: 'credit_card',
});

Environment Variables:

• ENABLE_SIGNOZ_LOGS: Enable SigNoz transport (default: true in production)
• LOG_LEVEL: Set log level (debug, info, warn, error)
• OTEL_SERVICE_NAME: Service name for log correlation
• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: SigNoz logs endpoint

Python Logging (pdf_processor_service/app/utils/logging.py)

Purpose: SigNoz-compatible structured logging with OpenTelemetry correlation.

Key Features:

• Structured JSON: SigNoz-compatible JSON formatting
• OpenTelemetry Correlation: Automatic trace and span ID correlation
• Service Context: Automatic service metadata injection
• Flexible Configuration: Environment-based configuration

Usage:

from app.utils.logging import logger, structured_logger

# Basic logging with context
logger.info("PDF processing started", extra={
    "document_id": "doc-123",
    "file_size": 2048576
})

# Structured logging
structured_logger.info(
    "pdf_extraction_completed",
    document_id="doc-123",
    processing_time=5.2,
    orders_extracted=15
)

✅ Current Status

• Single Implementation: ✅ instrumentation.cjs only
• Production & Development Ready: ✅ Works in all environments
• SigNoz Aligned: ✅ Follows official JavaScript documentation
• TypeScript Support: ✅ Astro/Vite handles module loading
• Backwards Compatible: ✅ Legacy environment variables still work
• Logging Integration: ✅ SigNoz-compatible logging for Node.js (Pino) and Python