DOCSEARCHbyAlgolia
Submit Docs

Elastic APM Node.js Agent

repository·main·Indexed 20 days ago

https://github.com/elastic/apm-agent-nodejs

The official Elastic APM agent for Node.js (version 4.18.0) automatically captures errors, tracing data, and performance metrics for Elastic Observability deployments. It includes support for TypeScript, ES Modules, and the OpenTelemetry Bridge for JS Tracing and Metrics APIs. The package also provides the HttpApmClient for low-level communication with the Elastic APM intake API v2.

Tokens
52.3K
Snippets
155
Records
268
Agent score
69%

What's inside elastic-apm-node

  1. Features of AWS Lambda instrumentation

    main

    The Elastic APM Node.js agent provides automatic instrumentation for AWS Lambda functions with the following capabilities:

    • Transaction Reporting: A transaction is reported for every function invocation.
    • Module Tracing: Traces all supported modules.
    • Trigger-specific Data: Transactions capture additional metadata for specific Lambda triggers, including:
      • API Gateway
      • SNS
      • SQS
      • S3 (when the trigger is a single event)
      • ELB
    • Error Reporting: Transactions are reported for invocations that fail due to a timeout, crash, uncaughtException, or unhandledRejection.

    Note: To report failures from timeouts, crashes, or unhandled exceptions, you must use APM agent v3.45.0 or later and Elastic’s APM Lambda extension version 1.4.0 or later.

  2. Explore Elastic APM Node.js Agent documentation

    main

    Once you have started the setup process, use the following resources to deepen your integration:

  4. What is the OpenTelemetry bridge?

    main

    The Elastic APM OpenTelemetry bridge allows you to use the vendor-neutral OpenTelemetry API (@opentelemetry/api) in your code while the Elastic Node.js APM agent handles the actual data processing and transmission. This prevents vendor lock-in by allowing you to add manual tracing or custom metrics using standard OpenTelemetry calls instead of the Elastic APM public API.

    Note: Both Tracing and Metrics integration are currently experimental.

    • Tracing integration: added in v3.34.0
    • Metrics integration: added in v3.45.0

    For full OpenTelemetry ecosystem functionality without the limitations of this bridge, consider using Elastic's OTel-native Node.js SDK (@elastic/opentelemetry-node).

  5. Understand the Elastic APM Node.js Agent API structure

    main

    The Elastic APM Node.js Agent API is organized into three primary layers based on the object you are interacting with:

    1. The Agent API: This is the entry point. When you require or import the elastic-apm-node module, you receive a singleton Agent instance (commonly referred to as apm). This object is used to manage the agent's lifecycle and to create transactions and spans.
    2. The Transaction API: These objects represent a single unit of work (e.g., an HTTP request). You obtain a Transaction instance by calling apm.startTransaction().
    3. The Span API: These objects represent a specific operation within a transaction (e.g., a database query or a function call). You obtain a Span instance by calling apm.startSpan().

  6. How to start the Elastic APM Node.js agent

    main

    To function correctly, the Elastic APM agent must be started before any other modules are required or imported. The agent works by interposing itself in the import process to instrument modules; if a module is loaded before the agent, it cannot be instrumented.

    When choosing a start method, prioritize:

    1. Ensuring the agent starts early enough in the process lifecycle.
    2. Having a convenient way to configure the agent (via options object or environment variables).

  7. Understand and override transaction `outcome`

    main

    The Elastic APM Node.js agent automatically determines the outcome of a transaction.

    Default Behavior

    • HTTP Transactions: A transaction is a success if the response status code is less than 500. A status code of 500 or greater is a failure.
    • Non-HTTP Transactions: These start with an outcome of unknown.

    Possible values are:

    • success: The operation succeeded.
    • failure: The operation failed.
    • unknown: The outcome could not be determined. Note that unknown outcomes are excluded from error rate calculations.

    Overriding Outcome

    You can manually force a specific outcome using transaction.setOutcome(outcome). This is useful for non-HTTP tasks where the agent cannot automatically detect success or failure.

    Supported values: "success", "failure", or "unknown".

    // Manually marking a background task as a failure
transaction.setOutcome('failure');

  8. Use Dynamic Configuration via Kibana

    main
    The Node.js Agent supports Central Configuration, which allows you to fine-tune specific configuration options at runtime via the APM app in Kibana. This feature is enabled by default using the centralConfig option. Options that can be changed without restarting the agent are marked with the dynamic configuration badge in the documentation.

  9. Understand the Elastic APM architecture components

    main

    The Elastic APM Node.js Agent is part of a larger ecosystem. To successfully monitor your application, the agent works in conjunction with the following components:

    • APM Server: Acts as the ingestion point for the agent's data.
    • Elasticsearch: The storage engine for the collected observability data.
    • Kibana: The visualization layer used to inspect traces, transactions, and errors.

    Before deploying, ensure you check the Agent and Server compatibility matrix to verify that your specific agent version is compatible with your APM Server version.

  10. How the Elastic APM Node.js Agent works

    main

    The Elastic APM Node.js Agent provides observability by automatically instrumenting supported frameworks and routers to record events like HTTP requests and database queries.

    Auto-instrumentation

    The agent patches modules as they are loaded to capture function calls and callbacks. For supported technologies, this process requires no code changes. The agent automatically links module function calls to their corresponding callback calls to measure duration and metadata (e.g., DB statements, HTTP URLs, parameters, and headers).

    Data Flow

    1. Agent: Captures events called Transactions and Spans.
    2. APM Server: Receives events from the agent and converts them into a format suitable for Elasticsearch.
    3. Elasticsearch: Stores the processed data.
    4. Kibana: Provides the APM app interface to visualize latency issues and error culprits.

    OpenTelemetry Alternative

    Elastic also supports OpenTelemetry for collecting logs, metrics, and trace signals. For full integration with the Elastic platform, consider using the EDOT Node.js SDK.

  11. Understand OpenTelemetry Bridge design and context management

    main

    The OpenTelemetry Bridge works by extending the agent's RunContext to support the OpenTelemetry interface Context API.

    Key design points:

    • Single Active Context Storage: The bridge uses OTelBridgeRunContext to provide a single source of truth for the active context, bridging between OTel and the APM agent's RunContext.
    • Span Tracking: The bridge translates OpenTelemetry context.setValue(SPAN_KEY, span) calls into the agent's this.enterSpan(span) method, and context.getValue(SPAN_KEY) into a wrapped OTelSpan.
    • Supported OTel Interfaces: The bridge primarily interacts with otel.context.* (context management) and otel.trace.* (span manipulation). It does not currently touch otel.propagation.* (trace-context propagation/Baggage) or otel.diag.* (though it hooks otel.diag to the agent logger if logLevel=trace).

  12. How the Elastic APM Node.js Agent singleton works

    main

    The Elastic APM Node.js agent is a singleton. You can obtain the agent instance by requiring elastic-apm-node or elastic-apm-node/start.

    To start the agent and capture the instance in a single step, use the .start() method:

    const apm = require('elastic-apm-node').start(...)

    Once started, you do not need to pass the agent instance around your application. Any part of your codebase can access the already-started singleton by simply requiring elastic-apm-node.