NewRelic::Agent - Perl Agent for NewRelic APM
version 0.0532
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);
This module provides bindings for the NewRelic Agent SDK.
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.
NEWRELIC_LICENSE_KEY
app_name
The name of your application.
This value is also automatically sourced from the NEWRELIC_APP_NAME environment variable.
NEWRELIC_APP_NAME
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.
perl
NEWRELIC_APP_LANGUAGE
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.
NEWRELIC_APP_LANGUAGE_VERSION
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.
init
Example:
$agent->embed_collector;
Initialize the connection to NewRelic.
$agent->init;
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.
WebTransaction
Uri
Returns the transaction's ID on success, else negative warning code or error code.
my $txn_id = $agent->begin_transaction;
Sets the transaction's name.
Returns 0 on success, else negative warning code or error code.
0
my $err_id = $agent->set_transaction_name($txn_id, 'Create Account');
Sets the transaction's request url. The query part of the url is automatically stripped from the url.
my $err_id = $agent->set_transaction_request_url($txn_id, 'api.myapp.com/users/123');
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).
2000
my $err_id = $agent->set_transaction_max_trace_segments($txn_id, 5000);
Sets the transaction's category name (.e.g Uri in "WebTransaction/Uri/<txn_name>").
my $err_id = $agent->set_transaction_category($txn_id, 'Custom');
Sets the transaction type to WebTransaction. This will automatically change the category to Uri.
my $err_id = $agent->set_transaction_type_web($txn_id);
Sets the transaction type to OtherTransaction. This will automatically change the category to Custom.
OtherTransaction
Custom
my $err_id = $agent->set_transaction_type_other($txn_id);
Sets a transaction attribute. Up to the first 50 attributes added are sent with each transaction.
my $err_id = $agent->add_transaction_attribute($txn_id, 'User-Agent', 'Mozilla/5.0 ...');
Identify an error that occurred during the transaction. The first identified error is sent with each transaction.
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", );
Identify the end of a transaction.
my $err_id = $agent->end_transaction($txn_id);
Record a custom metric.
my $err_id = $agent->record_metric('cache_miss_timing', 0.333333);
Record CPU user time in seconds and as a percentage of CPU capacity.
my $err_id = $agent->record_cpu_usage(2.1, 0.85);
Record the current amount of memory (in megabytes) being used.
my $err_id = $agent->record_memory_usage(745);
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.
my $seg_id = $agent->begin_generic_segment($txn_id, undef, 'Parse zip codes');
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.
?
my $seg_id = $agent->begin_datastore_segment( $txn_id, undef, 'users', 'selecting user', 'SELECT * FROM users WHERE id=?', 'get_user_account', );
Identify the beginning of a segment that performs an external service.
my $seg_id = $agent->begin_external_segment( $txn_id, undef, 'http://api.stripe.com/v1', 'tokenize credit card', );
Identify the end of a segment.
my $err_id = $agent->end_segment($txn_id, $seg_id);
Returns the license key that the agent has loaded. This is useful for diagnostic purposes.
my $license_key = $agent->get_license_key;
Returns the application name that the agent has loaded. This is useful for diagnostic purposes.
my $app_name = $agent->get_app_name;
Returns the application language that the agent has loaded. This is useful for diagnostic purposes.
my $app_language = $agent->get_app_language;
Returns the application language's version that the agent has loaded. This is useful for diagnostic purposes.
my $app_language_version = $agent->get_app_language_version;
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.
Ali Anari <ali@anari.me>
Slobodan Mišković <slobodan@miskovic.ca>
Tatsuhiko Miyagawa <miyagawa@bulknews.net>
Tim Bunce <tim.bunce@pobox.com>
Tim Bunce <tim@tigerlms.com>
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.
To install NewRelic::Agent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm NewRelic::Agent
CPAN shell
perl -MCPAN -e shell install NewRelic::Agent
For more information on module installation, please visit the detailed CPAN module installation guide.