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

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.

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.

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.

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

Increment a Custom metric.

NewRelic.increment_custom_metric("My/Metric")

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

Report a Custom event to NRDB.

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

Report a Custom metric.

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

Report a Dimensional Metric. Valid types: :count, :gauge, and :summary.

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

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

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

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

@spec 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.

@spec 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.