NAME

    NewRelic::Agent::FFI - Perl Agent for NewRelic APM

VERSION

    version 0.07

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

    This module provides bindings for the NewRelic
    <https://docs.newrelic.com/docs/agents/agent-sdk/getting-started/new-relic-agent-sdk>
    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
      <https://github.com/aanari/NewRelic-Agent/issues/2>! 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.

SEE ALSO

    NewRelic::Agent::FFI::Procedural

      Procedural interface, recommended over this one.

AUTHOR

    Graham Ollis <plicease@cpan.org>

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.

