search

newrelic / elixir_agent

New Relic's Open Source Elixir Agent
https://hex.pm/packages/new_relic_agent
Apache License 2.0
254 stars 97 forks source link
elixir open-source

readme

New Relic Open Source experimental project banner.

New Relic's Elixir agent

Build Status Hex.pm Version Hex Docs License

The experimental open-source Elixir agent allows you to monitor your Elixir applications with New Relic. It helps you track transactions, distributed traces, other parts of your application's behavior, and provides an overview of underlying BEAM activity.

View the Documentation

Support Statement

New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related topic in the community forum. You can find this project's topic/threads in the forum.

Contributing

We encourage your contributions to improve [project name]! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project. If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at opensource@newrelic.com.

A note about vulnerabilities: As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.

If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.

License

The open-source Elixir agent is licensed under the Apache 2.0 License.

Installation

Install the Hex package

Requirements:

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

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.

HTTP Client Settings

httpc client settings can be overridden if needed. For example, the HTTP connect timeout can be increased which can help alleviate errors related to timeouts connecting to New Relic:

config :new_relic_agent,
  app_name: "My App",
  license_key: "license_key",
  httpc_request_options: [connect_timeout: 5000]

For Elixir 1.15 and higher

Due to changes in the Elixir 1.15 Logger, additional logger configuration is needed for NewRelic to capture all errors. Update your logger configuration by setting handle_sasl_reports to true and adding NewRelic.ErrorLogger to your logger backends.

config :logger,
  handle_sasl_reports: true,
  backends: [:console, NewRelic.ErrorLogger]

Telemetry-based Instrumentation

Some common Elixir packages are auto-instrumented via telemetry

Agent features

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

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 ->
  NewRelic.connect_to_transaction(tx)
  # ...
end)

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...
end)

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 `MyModule.work/0`
  end
end

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

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
    # ...
  end
end

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
HTTPoison.get("http://www.example.com")

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:

NewRelic.stop_transaction()

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.

Disabling

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