Configuring the Agent SDK

BETA

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

NEWRELIC_ENABLE_SSL

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

Required for daemon-mode: No

NEWRELIC_ENABLE_HIGH_SECURITY

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

Required for daemon-mode: No

NEWRELIC_LOG_PROPERTIES_FILE

Format: <path/to/log4cplus.properties>

For example:

  • ~/.newrelic
  • <current working dir>

Required for daemon-mode: No

NEWRELIC_APP_SERVER_APDEX_T

Format: 0.25 (default is 0.5)

Required for daemon-mode: No

http_proxy

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"
    	export NEWRELIC_APP_LANGUAGE_VERSION="5.5"
    	

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

    ./newrelic-collector-client-daemon
  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
        }
        }
        newrelic_register_status_callback(newrelic_status_update);
        
  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:

    newrelic_register_message_handler(newrelic_message_handler);
  5. Initialize the library. For example:

    
        newrelic_init
        (
        my_license_key_string,
        "Hello World", 
        "Perl", 
        "5.5"
        );
        
  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:

Troubleshoot and ask questions about the Agent SDK in New Relic's Online Technical Community!

If you need additional help, get support at support.newrelic.com.