NAME
NewRelic::Agent - Perl Agent for NewRelic APM
VERSION
version 0.0532
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
lic-agent-sdk> 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,
'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;
BUGS
Please report any bugs or feature requests on the bugtracker website
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>
* Tatsuhiko Miyagawa <miyagawa@bulknews.net>
* Tim Bunce <tim.bunce@pobox.com>
* 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.