# New Relic's Elixir Agent

[![Build Status](](
[![ Version](](
[![Hex Docs](](

The Open-Source Elixir Agent allows you to monitor your `Elixir` applications with New Relic. It helps you track transactions, distributed traces and other parts of your application's behavior and provides an overview of underlying [BEAM activity](

[View the Documentation](

### Support Statement

New Relic has open-sourced this project to enable monitoring of `Elixir` applications. This project is provided AS-IS WITHOUT WARRANTY OR SUPPORT, although you can report issues and contribute to the project here on GitHub.

### Contributing

We'd love to get your contributions to improve the elixir agent! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. If you'd like to execute our corporate CLA, or if you have any questions, please drop us an email at []( 

## Installation

Install the [Hex package](

* Erlang/OTP 22
* Elixir 1.9

defp deps do
    {:new_relic_agent, "~> 1.0"}

## Configuration

You need to set a few required configuration keys so we can authenticate properly.

#### Via Application config

config :new_relic_agent,
  app_name: "My App",
  license_key: "license_key"

#### Via Environment variables

You can also configure these attributes via `ENV` vars, which helps keep secrets out of source code.


## Telemetry-based Instrumentation

Some common Elixir packages are auto-instrumented via [`telemetry`](

* [`Plug`]( See [NewRelic.Telemetry.Plug]( for details.
* [`Phoenix`]( See [NewRelic.Telemetry.Phoenix]( for details.
* [`Ecto`]( See [NewRelic.Telemetry.Ecto]( for details.
* [`Redix`]( See [NewRelic.Telemetry.Redix]( for details.

## Agent Features

There are a few agent features that can be enabled via configuration. Please see the documentation for more information.

* [Logs In Context](
* [Infinite Tracing](
* [Security Controls](

## Manual Instrumentation

#### Transactions

The `Plug` and `Phoenix` instrumentation automatically report a Transaction for each request.

These Transactions will follow across any process spawned and linked (ex: `Task.async`), but will _not_ follow a process that isn't linked (ex: `Task.Supervisor.async_nolink`).

To manually connect a Transaction to an unlinked process, you can use `NewRelic.get_transaction` and `NewRelic.connect_to_transaction`. See the docs for those functions for further details.

tx = NewRelic.get_transaction()

spawn(fn ->
  # ...

If you are using a `Task` to spawn work, you can use the pre-instrumented `NewRelic.Instrumented.Task` convienince module to make this easier. Just `alias` it in your module and all your Tasks will be instrumented. You may also use the functions directly.

alias NewRelic.Instrumented.Task

Task.Supervisor.async_nolink(MyTaskSupervisor, fn ->
  # This process wil be automatically connected to the Transaction...

#### Function Tracing

`NewRelic.Tracer` enables detailed Function tracing. Annotate a function and it'll show up as a span in Transaction Traces / Distributed Traces, and we'll collect aggregate stats about it. Install it by adding `use NewRelic.Tracer` to any module, and annotating any function with an `@trace` module attribute

defmodule MyModule do
  use NewRelic.Tracer

  @trace :work
  def work do
    # Will report as ``

#### Distributed Tracing

Requests to other services can be traced with the combination of an additional outgoing header and an `:external` tracer.

defmodule MyExternalService do
  use NewRelic.Tracer

  @trace {:request, category: :external}
  def request(method, url, headers) do
    NewRelic.set_span(:http, url: url, method: method, component: "HttpClient")
    headers = headers ++ NewRelic.distributed_trace_headers(:http)
    HttpClient.request(method, url, headers)

#### Pre-Instrumented Modules

`NewRelic.Instrumented.Mix.Task` To enable the Agent and record an Other Transaction during a `Mix.Task`, simply `use NewRelic.Instrumented.Mix.Task`. This will ensure the agent is properly started, records a Transaction, and is shut down.

defmodule Mix.Tasks.Example do
  use Mix.Task
  use NewRelic.Instrumented.Mix.Task

  def run(args) do
    # ...

`NewRelic.Instrumented.HTTPoison` Automatically wraps HTTP calls in a span, and adds an outbound header to track the request as part of a Distributed Trace.

alias NewRelic.Instrumented.HTTPoison

#### Other Transactions

You may start an "Other" Transaction for non-HTTP related work. This could used be while consuming from a message queue, for example.

To start an Other Transaction:

NewRelic.start_transaction(category, name)

And to stop the Transaction within the same process:


#### Adapters

There are a few adapters which leverage this agent to provide library / framework specific instrumentation. Note that these will eventually be replaced with `telemetry` based instrumentation.

* `Absinthe`

#### Disabling

If you want to disable the agent, you can do it in two different ways:

* Application config: `config :new_relic_agent, license_key: nil`
* Environment variables: `NEW_RELIC_HARVEST_ENABLED=false`