{"id":18289,"library":"elastic-apm-http-client","title":"elastic-apm-http-client","description":"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.","status":"active","version":"12.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/elastic/apm-nodejs-http-client","tags":["javascript","elastic","apm","http","client"],"install":[{"cmd":"npm install elastic-apm-http-client","lang":"bash","label":"npm"},{"cmd":"yarn add elastic-apm-http-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add elastic-apm-http-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for type checking (e.g., isString, isFunction).","package":"core-util-is","optional":false},{"reason":"Detects stream end/error for graceful shutdown.","package":"end-of-stream","optional":false},{"reason":"Safely serializes objects to JSON, avoiding circular reference errors.","package":"fast-safe-stringify","optional":false},{"reason":"Pipes streams together, auto-cleanup on error.","package":"pump","optional":false},{"reason":"Provides a modern streaming base class (used instead of core stream for compatibility).","package":"readable-stream","optional":false}],"imports":[{"note":"This package is CJS-only; there is no default ESM export. Use require().","wrong":"import Client from 'elastic-apm-http-client'","symbol":"default","correct":"const Client = require('elastic-apm-http-client')"},{"note":"ESM import works via Node.js interop; requires Node >=12 and \"type\": \"module\" or .mjs extension.","wrong":"","symbol":"default","correct":"import Client from 'elastic-apm-http-client'"},{"note":"The module exports a single constructor function as default. Named destructuring won't work.","wrong":"import { Client } from 'elastic-apm-http-client'","symbol":"default","correct":"const Client = require('elastic-apm-http-client')"}],"quickstart":{"code":"const Client = require('elastic-apm-http-client')\n\nconst client = new Client({\n  serverUrl: process.env.APM_SERVER_URL || 'http://127.0.0.1:8200',\n  secretToken: process.env.APM_SECRET_TOKEN || '',\n  apiKey: process.env.APM_API_KEY || '',\n  serviceName: 'My Service',\n  agentName: 'my-nodejs-agent',\n  agentVersion: '1.0.0',\n  userAgent: 'My Custom Agent/1.0.0'\n})\n\n// Example: Send a transaction\nclient.sendTransaction({\n  id: 'abc123',\n  trace_id: 'abc123',\n  transaction_id: 'abc123',\n  name: 'GET /api/users',\n  type: 'request',\n  duration: 42,\n  result: 'success',\n  timestamp: Date.now() * 1000, // microseconds\n  context: {\n    request: { method: 'GET', url: 'http://example.com/api/users' }\n  },\n  sampled: true\n})\n\nclient.flush(() => {\n  console.log('Data sent')\n})","lang":"javascript","description":"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."},"warnings":[{"fix":"Replace `hostname` and `port` with a single `serverUrl` string (e.g., `serverUrl: 'http://localhost:8200'`).","message":"In v6+, the options `hostname` and `port` are deprecated; use `serverUrl` instead.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Use `.then()` or `await` instead of a callback: `await client.sendTransaction(txn)`. For flush, use `client.flush()` which returns a Promise.","message":"In v8+, the `sendTransaction` and `sendSpan` methods no longer accept a callback; they return a Promise that resolves when the data is queued.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Remove `globalLabels` from constructor options and attach labels to each transaction/span via `context.tags` or similar.","message":"The `globalLabels` option is deprecated; use the `labels` property on individual metadata instead.","severity":"deprecated","affected_versions":">=10.0.0"},{"fix":"Multiply `Date.now()` by 1000: `timestamp: Date.now() * 1000`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure all four are provided: `agentName`, `agentVersion`, `serviceName`, `userAgent`.","cause":"Missing one or more required constructor options.","error":"Error: options.agentName, options.agentVersion, options.serviceName, and options.userAgent are required"},{"fix":"Double-check that the client was created with `new Client(options)` and use `sendTransaction` (capital S, capital T).","cause":"The client instance was not properly created or the method name is misspelled (e.g., case sensitivity).","error":"TypeError: client.sendTransaction is not a function"},{"fix":"Start the APM Server or update `serverUrl` to point to a valid server address.","cause":"APM Server is not running or not reachable at the configured URL.","error":"Error: connect ECONNREFUSED 127.0.0.1:8200"},{"fix":"Ensure the payload is a plain object without functions, Symbols, or circular references. Use JSON.parse(JSON.stringify(payload)) as a workaround.","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).","error":"Error: Unexpected token o in JSON at position 1"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}