polartrace

Package for monitoring and logging middleware for PolarTrace observability platform.

Installation

npm install polartrace

Quick Start

PolarTrace agent works automatically with zero code changes. Simply use environment variables and require the agent:

POLARTRACE_APP_NAME=<SERVICE_NAME> POLARTRACE_LICENSE_KEY=<API_KEY> node -r polartrace <main-file-name>.js

The agent will automatically:

• Initialize with your API key and service name from environment variables
• Attach middleware to Express applications
• Start collecting logs and traces
• Send data to the PolarTrace collector

Docker Example

FROM node:18

WORKDIR /app
COPY package*.json ./
RUN npm install

COPY . .

# Set environment variables
ENV POLARTRACE_APP_NAME=my-service
ENV POLARTRACE_LICENSE_KEY=your_api_key_here

# Run with PolarTrace agent
CMD ["node", "-r", "polartrace", "server.js"]

Or using docker-compose:

services:
  app:
    build: .
    environment:
      - POLARTRACE_APP_NAME=my-service
      - POLARTRACE_LICENSE_KEY=your_api_key_here
    command: node -r polartrace server.js

Configuration

All configuration is done via environment variables. No code changes required!

Required Environment Variables

• POLARTRACE_APP_NAME: Your service name (must be unique within your organization)
• POLARTRACE_LICENSE_KEY: Your PolarTrace API key

Optional Environment Variables

• POLARTRACE_ENABLE_CONSOLE_LOG: Set to "true" to enable console logging for debugging

Default Behavior

• Capture Headers: Enabled by default
• Capture Body: Enabled by default (sensitive fields are automatically redacted)
• Capture Query Parameters: Enabled by default
• Capture Console Logs: Enabled by default
• MongoDB Span Collection: Enabled by default

Contributing

Development Setup

Fork and clone the repository:

git clone [email protected]:your-username/polartrace-nodejs-agent.git
cd polartrace-nodejs-agent

Install dependencies:

npm install

Then you're ready to start developing.

Testing

PolarTrace uses a simple testing approach—no Docker required. Tests run with in-memory MongoDB and mocked HTTP.

Run all tests:

npm run test

Available test suites:

| Command | Description | |---------|-------------| | npm run unit | Unit tests (validation, sanitization, queue) | | npm run integration | Integration tests (Express, MongoDB, traces) | | npm run versioned | Version compatibility tests | | npm run lint | Lint source code | | npm run smoke | Quick smoke test (unit tests, fast) |

Before Submitting

1. Run npm run lint and fix any issues
2. Run npm run test to ensure all tests pass
3. Run npm run build to verify the build succeeds