NewRelic::Agent::FFI

(Deprecated) Perl Agent for NewRelic APM

SYNOPSIS

use NewRelic::Agent::FFI;

my $agent = NewRelic:Agent::FFI->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

NOTE: This module is deprecated. It is based on the NewRelic Agent SDK, which was only ever released as beta software. Please use NewFangle instead.

This module provides bindings for the NewRelic Agent SDK.

It is a drop in replacement for NewRelic::Agent that is implemented using FFI::Platypus instead of XS and C++. If you are writing new code, then I highly recommend the procedural interface instead: NewRelic::Agent::FFI::Procedural.

Why use NewRelic::Agent::FFI module instead of NewRelic::Agent?

• Powerful Alien technology

  This module uses Alien::nragent to either download the NR agent or to use a locally installed copy. The other module has a serious bug which will break when the install files are removed! You can choose the version of the NR SDK that you want to use instead of relying on the maintainer of NewRelic::Agent to do so.

• Possible license issues

  Related to the last point, the other module bundles the NR SDK, which may have legal risks (I am not a lawyer). In the very least I think goes against the Open Source philosophy of CPAN.

• No C++ compiler required!

  Since this module is built with powerful FFI and Platypus technology, you don't need to build XS bindings for it. The other module has its bindings written in C++, which is IMO unnecessary and doesn't add anything.

• Tests!

  The test suite for NewRelic::Agent is IMO insufficient to have confidence in it, especially if the SDK needs to be upgraded. This module comes with a number of tests that will at least make sure that the calls to NewRelic will not crash your application. The live test can even be configured (not on by default) to send data to NR so that you can be sure it works.

• Active Development

  At least as of this writing, this module is being actively developed. The other module has a number of unanswered open issues, bugs and pull requests.

Why use the other module instead of this one?

• This module is newer

  The other module has been around for longer, and may have been used in production more. Peoples will probably have noticed if it were broken by now.

CONSTRUCTOR

new

my $agent = NewRelic::Agent::FFI->new(%options);

Instantiates a new NewRelic::Agent client object. Options include:

• 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.

METHODS

Methods noted below that return $rc return 0 for success or non-zero for failure. See the NR SDK documentation for error codes.

embed_collector

$agent->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.

init

my $rc = $agent->init;

Initialize the connection to NewRelic.

begin_transaction

my $tx = $agent->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.

set_transaction_name

my $rc = $agent->set_transaction_name($tx, $name);

Sets the transaction name.

set_transaction_request_url

my $rc = $agent->set_transaction_request_url($tx, $url);

Sets the transaction URL.

set_transaction_max_trace_segments

my $rc = $agent->set_transaction_max_trace_segments($tx, $max);

Sets the maximum trace section for the transaction.

set_transaction_category

my $rc = $agent->set_transaction_category($tx, $category);

Sets the transaction category.

set_transaction_type_web

my $rc = $agent->set_transaction_type_web($tx);

Sets the transaction type to 'web'

set_transaction_type_other

my $rc = $agent->set_transaction_type_other($tx);

Sets the transaction type to 'other'

add_transaction_attribute

my $rc = $agent->add_transaction_attribute($tx, $key => $value);

Adds the given attribute (key/value pair) for the transaction.

notice_transaction_error

my $rc = $agent->notice_transaction_error($tx, $exception_type, $error_message, $stack_trace, $stack_frame_delimiter);

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

end_transaction

my $rc = $agent->end_transaction($tx);

record_metric

my $rc = $agent->record_metric($key => $value);

Records the given metric (key/value pair). The $value should be a floating point.

record_cpu_usage

my $rc = $agent->record_cpu_usage($cpu_user_time_seconds, $cpu_usage_percent);

Records the CPU usage. $cpu_user_time_seconds and $cpu_usage_percent are floating point values.

record_memory_usage

my $rc = $agent->record_memory_usage($memory_megabytes);

Records the memory usage. $memory_megabytes is a floating point value.

begin_generic_segment

my $seg = $agent->begin_generic_segment($tx, $parent_seg, $name);

Begins a new generic segment. $parent_seg is a parent segment id (undef no parent). $name is a string.

begin_datastore_segment

my $seg = $agent->begin_datastore_segment($tx, $parent_seg, $table, $operation, $sql, $sql_trace_rollup_name);

Begins a new datastore segment. $parent_seg is a parent segment id (undef no parent).

begin_external_segment

my $seg = $agent->begin_external_segment($tx, $parent_seg, $host, $name);

Begins a new external segment. $parent_seg is a parent segment id (undef no parent).

end_segment

my $rc = $agent->end_segment($tx, $seg);

End the given segment.

get_license_key

my $key = $agent->get_license_key;

Get the license key.

get_app_name

my $name = $agent->get_app_name;

Get the application name.

get_app_language

my $lang = $agent->get_app_language;

Get the language name (usually perl).

get_app_language_version

my $version = $agent->get_app_language_version;

Get the language version.

CAVEATS

Platform Limitations

The SDK binaries provided by New Relic only work on Linux x86_64. The binaries are labeled as a "beta" and were released in July 2016. It doesn't seem likely that New Relic will be releasing new versions of the SDK. The author of this module has had good success getting this module to work on Ubuntu Precise and Xenial, and heard from user feedback that it works with Bionic. I have heard that it does NOT work with CentOS 7. Your mileage may vary.

Not Fork Safe!

Bad things will happen if you call init before forking. So don't do that.

SEE ALSO

• NewRelic::Agent::FFI::Procedural

  Procedural interface, recommended over this one.

AUTHOR

Author: Graham Ollis plicease@cpan.org

Contributors:

Ville Skyttä (SCOP)

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Graham Ollis.

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