/ 
NewRelic-Agent-FFI-0.03
River stage zero No dependents
/ NewRelic::Agent::FFI::Procedural

NAME

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

VERSION

version 0.03

SYNOPSIS

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

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

my $tx_id = newrelic_transaction_begin;
...
my $err_id = newrelic_transaction_end $tx;

DESCRIPTION

This module provides bindings for the NewRelic Agent SDK.

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

Object oriented interface does represent or add anything

The 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 agent instances in the same process.

Object oriented interface is slower

Because the $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.

Functions aren't renamed

The object oriented version renames a number of its methods, meaning you have to look at the source code to understand what parts of the SDK you are actually calling. With this interface you can lookup the SDK functions in its documentation directly.

FUNCTIONS

newrelic_init

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

Initialize the connection to NewRelic.

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

newrelic_transaction_begin

my $tx = newrelic_transaction_begin;

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.

newrelic_transaction_set_name

my $status = newrelic_transaction_set_name $tx, $name;

Sets the transaction name.

newrelic_transaction_set_request_url

my $status = newrelic_transaction_set_request_url $tx, $url;

Sets the transaction URL.

newrelic_transaction_set_max_trace_segments

my $status = newrelic_transaction_set_max_trace_segments $tx, $max;

Sets the maximum trace section for the transaction.

newrelic_transaction_set_category

my $status = newrelic_transaction_set_category $tx, $category;

Sets the transaction category.

newrelic_transaction_set_type_web

my $status = newrelic_transaction_set_type_web $tx;

Sets the transaction type to 'web'

newrelic_transaction_set_type_other

my $status = newrelic_transaction_set_type_other $tx;

Sets the transaction type to 'other'

newrelic_transaction_add_attribute

my $status = newrelic_transaction_add_attribute $tx, $key => $value;

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

newrelic_transaction_notice_error

my $status = newrelic_transaction_notice_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.

newrelic_transaction_end

my $status = newrelic_transaction_end $tx;

newrelic_record_metric

my $status = newrelic_record_metric $key => $value;

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

newrelic_record_cpu_usage

my $status = newrelic_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.

newrelic_record_memory_usage

my $status = newrelic_record_memory_usage $memory_megabytes;

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

newrelic_segment_datastore_begin

my $seg = newrelic_segment_datastore_begin $tx, $parent_seg, $name;

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

newrelic_segment_generic_begin

my $seg = newrelic_segment_generic_begin $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).

newrelic_segment_external_begin

my $seg = newrelic_segment_external_begin $tx, $parent_seg, $host, $name;

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

newrelic_segment_end

my $status = newrelic_segment_end $tx, $seg;

End the given segment.

SEE ALSO

NewRelic::Agent::FFI

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.