view release on metacpan or  search on metacpan

lib/NewRelic/Agent/FFI/Procedural.pm  view on Meta::CPAN

our @EXPORT = sort grep /^newrelic_/i, keys %NewRelic::Agent::FFI::Procedural::;

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

NewRelic::Agent::FFI::Procedural - Procedural interface for NewRelic APM

=head1 VERSION

version 0.03

=head1 SYNOPSIS

 use NewRelic::Agent::FFI::Procedural;

 # enable embedded mode:
 newrelic_register_message_handler newrelic_message_handler;

 # initialize:
 newrelic_init
   'abc123'     # license key
   'REST API'   # app name
 ;

 # use it:
 my $tx = newrelic_transaction_begin;
 ...
 my $rc = newrelic_transaction_end $tx;

=head1 DESCRIPTION

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

This module provides bindings for the L<NewRelic|https://docs.newrelic.com/docs/agents/agent-sdk/getting-started/new-relic-agent-sdk> Agent SDK.

Unlike L<NewRelic::Agent::FFI>, this is NOT a drop in replacement for L<NewRelic::Agent>.  The author believes this interface is better.
In addition to the reasons the author believes L<NewRelic::Agent::FFI> to be better than L<NewRelic::Agent> (listed in the former's documentation),
the author believes this module to be better than L<NewRelic::Agent::FFI> because:

=over 4

=item Object oriented interface does represent or add anything

The L<NewRelic::Agent> instance that you create doesn't represent anything in the NewRelic Agent SDK.  In fact if you don't understand
how things work under the hood, you might be confused into believing that you can initialize multiple agent instances in the same process.

=item Object oriented interface is slower

Because the unused C<$agent> instance needs to be shifted off the stack before calling the underlying C code there is a lot more overhead in the
object oriented interface.

=item Functions aren't renamed

The object oriented version renames a number of its methods, so translating C/C++ example code is nearly impossible.
The procedural version uses the same function name and constants, so translating example code from other languages
is easy.

=item API is complete

This interface is more complete than the object oriented version.

=back

=head1 FUNCTIONS

All functions are exported by default.  You can explicitly specify just the functions that you want in the
usual L<Exporter> way if you prefer.

Functions that return a C<$rc> will return one of these codes (NEWRELIC_RETURN_CODE_OK is 0, the others
are negative values):

=over 4

=item NEWRELIC_RETURN_CODE_OK

=item NEWRELIC_RETURN_CODE_OTHER

=item NEWRELIC_RETURN_CODE_DISABLED

=item NEWRELIC_RETURN_CODE_INVALID_PARAM

=item NEWRELIC_RETURN_CODE_INVALID_ID

=item NEWRELIC_RETURN_CODE_TRANSACTION_NOT_STARTED

=item NEWRELIC_RETURN_CODE_TRANSACTION_IN_PROGRESS

=item NEWRELIC_RETURN_CODE_TRANSACTION_NOT_NAMED

=back

Functions that return a C<$tx> will return a transaction id on success, and a (negative) C<$rc> code on failure.

Functions that return a C<$seg> will return a segment id on success, and a (negative) C<$rc> code on failure.

Functions that return a C<$address> are the address to a C function that can be passed to other C<newrelic_> functions as appropriate.

For functions that take a C<$parent_seg> argument, you can pass in NEWRELIC_AUTOSCOPE or NEWRELIC_ROOT_SEGMENT instead of
a literal segment id.

For functions that take a C<$tx> argument, you can pass in NEWRELIC_AUTOSCOPE instead of a literal transaction id.

=head2 newrelic_init

 my $rc = newrelic_init $license_key, $app_name, $app_language, $app_language_version;

Initialize the connection to NewRelic.

=over 4

=item C<$license_key>

A valid NewRelic license key for your account.