Configuring the Agent SDK


After you install the New Relic Agent SDK, update your configuration so that your agent can run in the appropriate usage mode (daemon-mode or embedded-mode), as explained in this document.

Choosing a usage mode

In order to maintain communication with New Relic, the Agent SDK requires a thread to be started that harvests data once per minute. This means that your app will need to be able to start a thread that runs continuously as long as transactions are being executed.

For some languages, this is simple to do. For others, there is no mechanism to start a thread within the same process running your web transactions. For example, if you are running perl apps through Apache, then each perl script is a short-lived process that exits upon completion of the script. There is no ability to start up a thread that lives beyond the life of the script.

To solve this problem, New Relic designed the SDK so that your agent can run in two different modes: daemon-mode or embedded-mode.

  • In daemon-mode you will run the newrelic-collector-client-daemon that came with the Agent SDK as a standalone process. The daemon will collect and send data to New Relic.
  • In embedded-mode your application will start a thread that has the same responsibilities as the daemon. However, it will run within the same process as your transactions.

Using Agent SDK environmental variables

Adjust these values in your configuration as applicable for your selected mode (daemon-mode or embedded-mode).

NEWRELIC_LICENSE_KEY (required for daemon-mode)

Format: <your license key>

NEWRELIC_APP_NAME (required for daemon-mode)

Format: "Hello World"

NEWRELIC_APP_LANGUAGE (required for daemon-mode)

Format: "Perl"

NEWRELIC_APP_LANGUAGE_VERSION (required for daemon-mode)

Format: 5.18.2


Format: 0 (disabled) or 1 (enabled, default)

Required for daemon-mode: No


Format: 0 (disabled, default) or 1 (enabled)

Required for daemon-mode: No


Format: <path/to/>

For example:

  • ~/.newrelic
  • <current working dir>

Required for daemon-mode: No


Format: 0.25 (default is 0.5)

Required for daemon-mode: No


Format: "http://<name>:<passwd>@<proxy>:<port>"

Required for daemon-mode: No

Running in daemon-mode

The SDK daemon will run with the privileges of the application starting it, which may be elevated. For example, if the daemon is started by Apache, it may run as root.

  1. Set the required environment variables before launching the daemon, including:

    	export NEWRELIC_LICENSE_KEY=<your license key>
    	export NEWRELIC_APP_NAME="Hello World"
    	export NEWRELIC_APP_LANGUAGE="Perl"

    Start the daemon by executing the following command in a terminal window:

  2. Start your app, and then wait a few minutes to start seeing data in New Relic.

Running in embedded-mode

To run in embedded-mode, embed the collector client in your app by following these steps:

  1. Include the newrelic_collector_client.h and newrelic_common.h header files.
  2. Link your application to the libnewrelic-common and libnewrelic-collector-client libraries.
  3. Optional: Create a function to receive status change notifications. For example:

        void newrelic_status_update(int status)
        if (status == NEWRELIC_STATUS_CODE_SHUTDOWN)
        // do something when the agent shuts down
  4. To send data to New Relic when transactions are completed, register a callback that has already been defined inside the libnewrelic-collector-client library:

  5. Initialize the library. For example:

        "Hello World", 
  6. Optional: Shut down the connection to New Relic. For example:

        newrelic_request_shutdown("insert your reason here");
  7. Start your app, and then wait a few minutes to start seeing data in New Relic.

For more help

Additional documentation resources include:

Recommendations for learning more:

  • See the Docs site's landing page for APM agent SDK documentation.
  • Browse New Relic's Explorers Hub for community discussions about the APM agent SDK.
  • Use your preferred search engine to find other New Relic resources.