elastic-apm-http-client

12.0.0 verified Sat Apr 25 auth: no javascript

A low-level HTTP client for communicating with the Elastic APM intake API. Version 12.0.0 supports the intake API v2 (for v1 use <6.x). It handles ndjson serialization, gzip compression, and streaming to the APM Server. Designed as a building block for custom APM agents, not for direct use in applications; the official Elastic APM Node.js agent is recommended instead. Released under MIT license, with frequent updates.

Common errors

error Error: options.agentName, options.agentVersion, options.serviceName, and options.userAgent are required ↓

cause Missing one or more required constructor options.

fix

Ensure all four are provided: agentName, agentVersion, serviceName, userAgent.

error TypeError: client.sendTransaction is not a function ↓

cause The client instance was not properly created or the method name is misspelled (e.g., case sensitivity).

fix

Double-check that the client was created with new Client(options) and use sendTransaction (capital S, capital T).

error Error: connect ECONNREFUSED 127.0.0.1:8200 ↓

cause APM Server is not running or not reachable at the configured URL.

fix

Start the APM Server or update serverUrl to point to a valid server address.

error Error: Unexpected token o in JSON at position 1 ↓

cause Trying to send an object that is not serializable or has circular references (though fast-safe-stringify helps, it may still fail on certain values).

fix

Ensure the payload is a plain object without functions, Symbols, or circular references. Use JSON.parse(JSON.stringify(payload)) as a workaround.

Warnings

breaking In v6+, the options `hostname` and `port` are deprecated; use `serverUrl` instead. ↓

fix Replace `hostname` and `port` with a single `serverUrl` string (e.g., `serverUrl: 'http://localhost:8200'`).

breaking In v8+, the `sendTransaction` and `sendSpan` methods no longer accept a callback; they return a Promise that resolves when the data is queued. ↓

fix Use `.then()` or `await` instead of a callback: `await client.sendTransaction(txn)`. For flush, use `client.flush()` which returns a Promise.

deprecated The `globalLabels` option is deprecated; use the `labels` property on individual metadata instead. ↓

fix Remove `globalLabels` from constructor options and attach labels to each transaction/span via `context.tags` or similar.

gotcha The `timestamp` field in transactions and spans must be in microsecond resolution (Unix epoch microseconds). Supplying milliseconds will cause incorrect timing on the APM Server. ↓

fix Multiply `Date.now()` by 1000: `timestamp: Date.now() * 1000`.

Install

npm install elastic-apm-http-client

yarn add elastic-apm-http-client

pnpm add elastic-apm-http-client

Imports

default

wrong

import Client from 'elastic-apm-http-client'

correct

const Client = require('elastic-apm-http-client')

This package is CJS-only; there is no default ESM export. Use require().

default
```
import Client from 'elastic-apm-http-client'
```
ESM import works via Node.js interop; requires Node >=12 and "type": "module" or .mjs extension.
default
wrong
```
import { Client } from 'elastic-apm-http-client'
```
correct
```
const Client = require('elastic-apm-http-client')
```
The module exports a single constructor function as default. Named destructuring won't work.

Quickstart

Shows how to instantiate the client with required config and send a transaction object. Includes authentication via environment variables, common pitfalls like timestamp in microseconds, and proper flush.

const Client = require('elastic-apm-http-client')

const client = new Client({
  serverUrl: process.env.APM_SERVER_URL || 'http://127.0.0.1:8200',
  secretToken: process.env.APM_SECRET_TOKEN || '',
  apiKey: process.env.APM_API_KEY || '',
  serviceName: 'My Service',
  agentName: 'my-nodejs-agent',
  agentVersion: '1.0.0',
  userAgent: 'My Custom Agent/1.0.0'
})

// Example: Send a transaction
client.sendTransaction({
  id: 'abc123',
  trace_id: 'abc123',
  transaction_id: 'abc123',
  name: 'GET /api/users',
  type: 'request',
  duration: 42,
  result: 'success',
  timestamp: Date.now() * 1000, // microseconds
  context: {
    request: { method: 'GET', url: 'http://example.com/api/users' }
  },
  sampled: true
})

client.flush(() => {
  console.log('Data sent')
})