@devskin/agent

DevSkin APM Agent - Application Performance Monitoring for Node.js

Installation

npm install @devskin/agent

Quick Start

1. Initialize the Agent

Initialize the agent before other imports in your application entry point:

// app.js or index.js
const { init, startAgent, expressMiddleware } = require('@devskin/agent');

const agent = init({
  serverUrl: 'https://admin-monitoring.devskin.com',
  apiKey: 'your-api-key',
  serviceName: 'my-service',
  environment: process.env.NODE_ENV || 'production',

  // Optional configuration
  sampleRate: 1.0,        // Sample 100% of traces
  instrumentHttp: true,   // Auto-instrument HTTP calls
  instrumentExpress: true,// Auto-instrument Express
  debug: false
});

// Start the agent
await startAgent();

2. Add Express Middleware

const express = require('express');
const { expressMiddleware } = require('@devskin/agent');

const app = express();

// Add APM middleware (captures all routes automatically)
app.use(expressMiddleware(agent));

app.get('/api/users', async (req, res) => {
  // This request is automatically traced!
  const users = await db.query('SELECT * FROM users');
  res.json(users);
});

app.listen(3000);

Manual Span Creation

For custom business logic tracing:

const { SpanBuilder, SpanKind } = require('@devskin/agent');

async function processOrder(orderId) {
  const agent = getAgent();
  const span = agent.createSpan('processOrder', SpanKind.INTERNAL);

  span.setAttribute('order.id', orderId);

  try {
    const order = await db.query('SELECT * FROM orders WHERE id = $1', [orderId]);
    span.setAttribute('order.amount', order.amount);
    span.setOk();
    return order;
  } catch (error) {
    span.recordError(error);
    throw error;
  } finally {
    span.end();
  }
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | serverUrl | string | Required | DevSkin server URL | | apiKey | string | Required | API key for authentication | | serviceName | string | Required | Name of your service | | serviceVersion | string | '1.0.0' | Version of your service | | environment | string | 'production' | Environment name | | sampleRate | number | 1.0 | Sampling rate (0.0 to 1.0) | | instrumentHttp | boolean | true | Auto-instrument HTTP calls | | instrumentExpress | boolean | true | Auto-instrument Express | | debug | boolean | false | Enable debug logging | | flushInterval | number | 5000 | Interval to flush spans (ms) | | maxBatchSize | number | 100 | Max spans per batch |

Middleware Options

app.use(expressMiddleware(agent, {
  // Paths to ignore
  ignorePaths: ['/health', '/metrics'],
  
  // Custom request hook
  requestHook: (span, req) => {
    span.setAttribute('user.id', req.user?.id);
  },
  
  // Custom response hook
  responseHook: (span, req, res) => {
    span.setAttribute('response.cached', res.getHeader('X-Cache') === 'HIT');
  }
}));

Span Kinds

| Kind | Description | |------|-------------| | SpanKind.INTERNAL | Internal operation | | SpanKind.SERVER | Server-side handling of a request | | SpanKind.CLIENT | Client-side HTTP request | | SpanKind.PRODUCER | Message producer | | SpanKind.CONSUMER | Message consumer |

Distributed Tracing

The agent automatically propagates trace context via W3C Trace Context headers:

• traceparent: Standard W3C header for trace propagation
• x-devskin-trace-id: DevSkin custom header

API Reference

init(config)

Initialize the agent with configuration. Returns the agent instance.

startAgent()

Start the agent and begin collecting traces. Returns a Promise.

stopAgent()

Stop the agent and flush remaining data. Returns a Promise.

getAgent()

Get the current agent instance. Returns null if not initialized.

expressMiddleware(agent, options)

Create Express middleware for automatic request tracing.

agent.createSpan(name, kind, parentSpan)

Create a new span for custom tracing.

agent.recordMetric(name, value, tags)

Record a custom metric.

License

MIT