NewRelic (New Relic Elixir Agent v1.27.1) View Source

New Relic Agent - Public API

Link to this section Summary

Functions

Report custom attributes on the current Transaction

Advanced: Call to manually connect the current process to a Transaction. Pass in a reference returned by NewRelic.get_transaction()

See NewRelic.DistributedTrace.distributed_trace_headers/1.

Advanced: Call to manually disconnect the current proccess from the current Transaction.

You must manually instrument outgoing HTTP calls to connect them to a Distributed Trace.

Call to exclude the current process from being part of the Transaction.

Advanced: Return a Transaction reference that can be used to manually connect a process to a Transaction with NewRelic.connect_to_transaction()

Call within a transaction to prevent it from reporting.

Increment a Custom metric.

Define an "Other" transaction with the given block. The return value of the block is returned.

Report a Custom event to NRDB.

Report a Custom metric.

To get detailed information about a particular process, you can install a Process sampler. You must tell the Agent about your process from within the process.

Store information about the type of work the current span is doing.

Set the name of the current transaction.

Start an "Other" Transaction.

Stop an "Other" Transaction.

Link to this section Functions

Link to this function

add_attributes(custom_attributes)

View Source

Report custom attributes on the current Transaction

Reporting nested data structures is supported by auto-flattening them into a list of key-value pairs.

NewRelic.add_attributes(foo: "bar")
  # "foo" => "bar"

NewRelic.add_attributes(map: %{foo: "bar", baz: "qux"})
  # "map.foo" => "bar"
  # "map.baz" => "qux"
  # "map.size" => 2

NewRelic.add_attributes(list: ["a", "b", "c"])
  # "list.0" => "a"
  # "list.1" => "b"
  # "list.2" => "c"
  # "list.length" => 3

Notes:

  • Nested Lists and Maps are truncated at 10 items since there are a limited number of attributes that can be reported on Transaction events
Link to this function

connect_to_transaction(ref)

View Source

Advanced: Call to manually connect the current process to a Transaction. Pass in a reference returned by NewRelic.get_transaction()

Only use this when there is no auto-discoverable connection (ex: the process was spawned without links or the logic is within a message handling callback).

This connection will persist until the process exits or NewRelic.disconnect_from_transaction() is called.

Link to this function

create_distributed_trace_payload(type)

View Source
This function is deprecated. Use distributed_trace_headers/1 instead.

See NewRelic.DistributedTrace.distributed_trace_headers/1.

Link to this function

disconnect_from_transaction()

View Source

Advanced: Call to manually disconnect the current proccess from the current Transaction.

Link to this function

distributed_trace_headers(type)

View Source

You must manually instrument outgoing HTTP calls to connect them to a Distributed Trace.

The agent will automatically read request headers and detect if the request is a part of an incoming Distributed Trace, but outgoing requests need an extra header:

HTTPoison.get(url, ["x-api-key": "secret"] ++ NewRelic.distributed_trace_headers(:http))

Notes:

  • Call NewRelic.distributed_trace_headers immediately before making the request since calling the function marks the "start" time of the request.
Link to this function

exclude_from_transaction()

View Source

Call to exclude the current process from being part of the Transaction.

Advanced: Return a Transaction reference that can be used to manually connect a process to a Transaction with NewRelic.connect_to_transaction()

Call within a transaction to prevent it from reporting.

def index(conn, _) do
  NewRelic.ignore_transaction()
  send_resp(conn, 200, "Health check OK")
end
Link to this function

increment_custom_metric(name, count \\ 1)

View Source

Increment a Custom metric.

NewRelic.increment_custom_metric("My/Metric")
Link to this macro

other_transaction(category, name, list)

View Source (macro)

Define an "Other" transaction with the given block. The return value of the block is returned.

See start_transaction and stop_transaction for more details about Transactions.

Example:

defmodule Worker do
  use NewRelic.Tracer

  def process_messages do
    NewRelic.other_transaction("Worker", "ProcessMessages") do
      # ...
    end
  end
end
Link to this function

report_custom_event(type, attributes)

View Source

Report a Custom event to NRDB.

NewRelic.report_custom_event("EventType", %{"foo" => "bar"})
Link to this function

report_custom_metric(name, value)

View Source

Report a Custom metric.

NewRelic.report_custom_metric("My/Metric", 123)

To get detailed information about a particular process, you can install a Process sampler. You must tell the Agent about your process from within the process.

For a GenServer, this function call should be made in the init function:

defmodule ImportantProcess do
  use GenServer
  def init(:ok) do
    NewRelic.sample_process
    {:ok, %{}}
  end
end

Once installed, the agent will report ElixirSample events with:

  • category = "Process"
  • message_queue_length
  • reductions
  • memory_kb
Link to this function

set_span(type, attributes)

View Source

Store information about the type of work the current span is doing.

Options:

  • :generic, custom: attributes
  • :http, url: url, method: method, component: component
  • :datastore, statement: statement, instance: instance, address: address, hostname: hostname, component: component
Link to this function

set_transaction_name(name)

View Source

Set the name of the current transaction.

The first segment will be treated as the Transaction namespace, and commonly contains the name of the framework.

Notes:

  • At least 2 segments are required to light up the Transactions UI in APM

In the following example, you will see /custom/transaction/name in the Transaction list.

NewRelic.set_transaction_name("/Plug/custom/transaction/name")
Link to this function

start_transaction(category, name)

View Source

Specs

start_transaction(String.t(), String.t()) :: :ok

Start an "Other" Transaction.

This will begin monitoring the current process as an "Other" Transaction (ie: Not a "Web" Transaction). The first argument will be considered the "category", the second is the "name".

Examples:

NewRelic.start_transaction("GenStage", "MyConsumer/EventType")
NewRelic.start_transaction("Task", "TaskName")

Notes:

  • Don't use this to track Web Transactions - Plug based HTTP servers are auto-instrumented based on telemetry events.
  • Do not use this for processes that live a very long time, doing so will risk a memory leak tracking attributes in the transaction!
  • You can't start a new transaction within an existing one. Any process spawned inside a transaction belongs to that transaction.
  • If multiple transactions are started in the same Process, you must call NewRelic.stop_transaction() to mark the end of the transaction.

Specs

stop_transaction() :: :ok

Stop an "Other" Transaction.

If multiple transactions are started in the same Process, you must call NewRelic.stop_transaction() to mark the end of the transaction.