NAME

NewRelic::Agent - Perl Agent for NewRelic APM

VERSION

version 0.0530

SYNOPSIS

use NewRelic::Agent;

my $agent = NewRelic:Agent->new(
    license_key => 'abc123',
    app_name    => 'REST API',
);

$agent->embed_collector;
$agent->init;
my $txn_id = $agent->begin_transaction;
...
my $err_id = $agent->end_transaction($txn_id);

DESCRIPTION

This module provides bindings for the NewRelic Agent SDK.

METHODS

new

Instantiates a new NewRelic::Agent client object.

my $agent = NewRelic::Agent->new(
    license_key          => $license_key,
    app_name             => $app_name,
    app_language         => $app_language,         #optional
    app_language_version => $app_language_version, #optional
);

Parameters

• • license_key

    A valid NewRelic license key for your account.

    This value is also automatically sourced from the NEWRELIC_LICENSE_KEY environment variable.

• • app_name

    The name of your application.

    This value is also automatically sourced from the NEWRELIC_APP_NAME environment variable.

• • app_language

    The language that your application is written in.

    This value defaults to perl, and can also be automatically sourced from the NEWRELIC_APP_LANGUAGE environment variable.

• • app_language_version

    The version of the language that your application is written in.

    This value defaults to your perl version, and can also be automatically sourced from the NEWRELIC_APP_LANGUAGE_VERSION environment variable.

embed_collector

Embeds the collector agent for harvesting NewRelic data. This should be called before init, if the agent is being used in Embedded mode and not Daemon mode.

Example:

$agent->embed_collector;

init

Initialize the connection to NewRelic.

Example:

$agent->init;

begin_transaction

Identifies the beginning of a transaction, which is a timed operation consisting of multiple segments. By default, transaction type is set to WebTransaction and transaction category is set to Uri.

Returns the transaction's ID on success, else negative warning code or error code.

Example:

my $txn_id = $agent->begin_transaction;

set_transaction_name

Sets the transaction's name.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->set_transaction_name($txn_id, 'Create Account');

set_transaction_request_url

Sets the transaction's request url. The query part of the url is automatically stripped from the url.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->set_transaction_request_url($txn_id, 'api.myapp.com/users/123');

set_transaction_max_trace_segments

Sets the maximum number of trace segments allowed in a transaction trace. By default, the maximum is set to 2000, which means the first 2000 segments in a transaction will create trace segments if the transaction exceeds the trace theshold (4 x apdex_t).

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->set_transaction_max_trace_segments($txn_id, 5000);

set_transaction_category

Sets the transaction's category name (.e.g Uri in "WebTransaction/Uri/<txn_name>").

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->set_transaction_category($txn_id, 'Custom');

set_transaction_type_web

Sets the transaction type to WebTransaction. This will automatically change the category to Uri.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->set_transaction_type_web($txn_id);

set_transaction_type_other

Sets the transaction type to OtherTransaction. This will automatically change the category to Custom.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->set_transaction_type_other($txn_id);

add_transaction_attribute

Sets a transaction attribute. Up to the first 50 attributes added are sent with each transaction.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->add_transaction_attribute($txn_id, 'User-Agent', 'Mozilla/5.0 ...');

notice_transaction_error

Identify an error that occurred during the transaction. The first identified error is sent with each transaction.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->notice_transaction_error(
    $txn_id,
    'Runtime error',
    'Illegal division by zero',
    "Illegal division by zero at div0.pl line 4.\nmain::run() called at div0.pl line7",
    "\n",
);

end_transaction

Identify the end of a transaction.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->end_transaction($txn_id);

record_metric

Record a custom metric.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->record_metric('cache_miss_timing', 0.333333);

record_cpu_usage

Record CPU user time in seconds and as a percentage of CPU capacity.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->record_cpu_usage(2.1, 0.85);

record_memory_usage

Record the current amount of memory (in megabytes) being used.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->record_memory_usage(745);

begin_generic_segment

Identify the beginning of a segment that performs a generic operation. This type of segment does not create metrics, but can show up in a transaction trace if a transaction is slow enough.

Returns the segment's ID on success, else negative warning code or error code.

Example:

my $seg_id = $agent->begin_generic_segment($txn_id, undef, 'Parse zip codes');

begin_datastore_segment

Identify the beginning of a segment that performs a database operation. This uses the default sql_obfuscator that strips the SQL string literals and numeric sequences, replacing them with the ? character.

Returns the segment's ID on success, else negative warning code or error code.

Example:

my $seg_id = $agent->begin_datastore_segment(
    $txn_id,
    undef,
    'users',
    'selecting user',
    'SELECT * FROM users WHERE id=?',
    'get_user_account',
);

begin_external_segment

Identify the beginning of a segment that performs an external service.

Returns the segment's ID on success, else negative warning code or error code.

Example:

my $seg_id = $agent->begin_external_segment(
    $txn_id,
    undef,
    'http://api.stripe.com/v1',
    'tokenize credit card',
);

end_segment

Identify the end of a segment.

Returns 0 on success, else negative warning code or error code.

Example:

my $err_id = $agent->end_segment($txn_id, $seg_id);

get_license_key

Returns the license key that the agent has loaded. This is useful for diagnostic purposes.

Example:

my $license_key = $agent->get_license_key;

get_app_name

Returns the application name that the agent has loaded. This is useful for diagnostic purposes.

Example:

my $app_name = $agent->get_app_name;

get_app_language

Returns the application language that the agent has loaded. This is useful for diagnostic purposes.

Example:

my $app_language = $agent->get_app_language;

get_app_language_version

Returns the application language's version that the agent has loaded. This is useful for diagnostic purposes.

Example:

my $app_language_version = $agent->get_app_language_version;

CAVEATS

The NewRelic Agent CDK on which this module is based never left beta and is no longer supported by NewRelic.

SEE ALSO

• NewFangle

  An unofficial NewRelic SDK based on their C-SDK

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/aanari/NewRelic-Agent/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Ali Anari ali@anari.me

CONTRIBUTORS

• Slobodan Mišković slobodan@miskovic.ca
• Tim Bunce tim@tigerlms.com

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Ali Anari.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.