@devskin/agent

DevSkin APM Agent - Application Performance Monitoring for Node.js

Installation

``bash
npm install @devskin/agent
`

Quick Start

$3

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

`javascript
// 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();
`

$3

`javascript
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:

`javascript
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

`javascript
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

$3

Initialize the agent with configuration. Returns the agent instance.

$3

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

$3

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

$3

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

$3

Create Express middleware for automatic request tracing.

$3

Create a new span for custom tracing.

$3

Record a custom metric.

License

MIT