@spec add_attributes(attributes :: Keyword.t()) :: any()

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" => 3copy

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

@spec add_span_attributes(attributes :: Keyword.t()) :: any()

Add additional attributes to the current Span (not the current Transaction).

Useful for reporting additional information about work being done in, for example, a function being traced with @trace

Example

NewRelic.add_span_attributes(some: "attribute")copy

@spec connect_to_transaction(tx_ref()) :: any()

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

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/0 is called.

Example:

tx = NewRelic.get_transaction()

spawn(fn ->
  NewRelic.connect_to_transaction(tx)
  # ...
end)copy

See: NewRelic.distributed_trace_headers/1

@spec disconnect_from_transaction() :: any()

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

@spec distributed_trace_headers(:http) :: [{key :: String.t(), value :: String.t()}]

@spec distributed_trace_headers(:other) :: map()

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

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

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

Notes

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

@spec exclude_from_transaction() :: any()

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

Example:

Task.async(fn ->
  NewRelic.exclude_from_transaction()
  Work.wont_be_included()
end)copy

@spec get_transaction() :: tx_ref()

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

@spec ignore_transaction() :: any()

Call within a transaction to prevent it from reporting.

Example

def index(conn, _) do
  NewRelic.ignore_transaction()
  send_resp(conn, 200, "Health check OK")
endcopy

@spec increment_custom_metric(name :: String.t(), count :: integer()) :: any()

Increment a Custom metric.

Example

NewRelic.increment_custom_metric("My/Metric")copy

@spec notice_error(Exception.t(), Exception.stacktrace()) :: any()

Report an Exception inside a Transaction.

This should only be used when you rescue an exception inside a Transaction, but still want to report it. All un-rescued exceptions are already reported as errors.

Example

try do
  raise RuntimeError
rescue
  exception -> NewRelic.notice_error(exception, __STACKTRACE__)
endcopy

Record an "Other" Transaction within the given block. The return value of the block is returned.

See start_transaction/2 and stop_transaction/0 for more details about Transactions.

Example

defmodule Worker do
  use NewRelic.Tracer

  def process_messages do
    NewRelic.other_transaction("Worker", "ProcessMessages") do
      # ...
    end
  end
endcopy

@spec report_custom_event(type :: String.t(), event :: map()) :: any()

@spec report_custom_event(name :: String.t(), value :: number()) :: any()

Report a Custom event to NRDB.

Example

NewRelic.report_custom_event("EventType", %{"foo" => "bar"})copy

Report a Custom metric.

Example

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

@spec report_dimensional_metric(
  type :: :count | :gauge | :summary,
  name :: String.t(),
  value :: number(),
  attributes :: map()
) :: any()

Report a Dimensional Metric.

Valid types: :count, :gauge, and :summary.

Example

NewRelic.report_dimensional_metric(:count, "my_metric_name", 1, %{some: "attributes"})copy

@spec sample_process() :: any()

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
endcopy

Once installed, the agent will report ElixirSample events with:

• category = "Process"
• message_queue_length
• reductions
• memory_kb

@spec set_span(:generic, attributes :: Keyword.t()) :: any()

@spec set_span(:http, url: String.t(), method: String.t(), component: String.t()) ::
  any()

@spec set_span(:datastore,
  statement: String.t(),
  instance: String.t(),
  address: String.t(),
  hostname: String.t(),
  component: String.t()
) :: any()

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

Examples

NewRelic.set_span(:generic, some: "attribute")

NewRelic.set_span(:http, url: "https://elixir-lang.org", method: "GET", component: "HttpClient")

NewRelic.set_span(:datastore, statement: statement, instance: instance, address: address,
hostname: hostname, component: component)copy

@spec set_transaction_name(String.t()) :: any()

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")copy

Record a "Span" within the given block. The return value of the block is returned.

NewRelic.span("do.some_work", user_id: "abc123") do
  # do some work
endcopy

Note: You can also use @trace annotations to instrument functions without modifying code.

@spec start_transaction(String.t(), String.t()) :: any()

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

The third argument is an optional map of headers that will connect this Transaction to an existing Distributed Trace. You can provide W3C "traceparent" and "tracestate" headers or another New Relic agent's "newrelic" header.

The Transaction will end when the process exits, or when you call NewRelic.stop_transaction()

Examples

NewRelic.start_transaction("GenStage", "MyConsumer/EventType")
NewRelic.start_transaction("Task", "TaskName")
NewRelic.start_transaction("WebSocket", "Handler", %{"newrelic" => "..."})copy

Notes

• Don't use this to track Web Transactions - Plug based HTTP servers are auto-instrumented based on telemetry events.
• If multiple transactions are started in the same Process, you must call NewRelic.stop_transaction/0 to mark the end of the Transaction.

@spec start_transaction(String.t(), String.t(), headers :: map()) :: any()

See NewRelic.OtherTransaction.start_transaction/3.

@spec stop_transaction() :: any()

Stop an "Other" Transaction.

If multiple Transactions are started in the same Process, you must call NewRelic.stop_transaction/0 to mark the end of the Transaction.