{"id":13651231,"url":"https://github.com/newrelic/elixir_agent","last_synced_at":"2025-10-21T19:02:13.028Z","repository":{"id":32952763,"uuid":"144901017","full_name":"newrelic/elixir_agent","owner":"newrelic","description":"New Relic's Open Source Elixir Agent","archived":false,"fork":false,"pushed_at":"2025-03-05T06:32:37.000Z","size":1566,"stargazers_count":258,"open_issues_count":9,"forks_count":102,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-19T10:09:15.123Z","etag":null,"topics":["elixir","open-source"],"latest_commit_sha":null,"homepage":"https://hex.pm/packages/new_relic_agent","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/newrelic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-15T20:38:11.000Z","updated_at":"2025-04-14T16:28:04.000Z","dependencies_parsed_at":"2024-06-18T13:58:25.235Z","dependency_job_id":"eb307340-9537-479d-be2e-e48f4b5ac4fa","html_url":"https://github.com/newrelic/elixir_agent","commit_stats":{"total_commits":533,"total_committers":33,"mean_commits":"16.151515151515152","dds":0.3358348968105066,"last_synced_commit":"3081412ceb1315f50629fe3323c2c5f32cc7f505"},"previous_names":[],"tags_count":118,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newrelic%2Felixir_agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newrelic%2Felixir_agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newrelic%2Felixir_agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/newrelic%2Felixir_agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/newrelic","download_url":"https://codeload.github.com/newrelic/elixir_agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250333871,"owners_count":21413472,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","open-source"],"created_at":"2024-08-02T02:00:46.856Z","updated_at":"2025-10-21T19:02:12.564Z","avatar_url":"https://github.com/newrelic.png","language":"Elixir","funding_links":[],"categories":["Tracing"],"sub_categories":[],"readme":"\u003ca href=\"https://opensource.newrelic.com/oss-category/#new-relic-experimental\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/newrelic/opensource-website/raw/main/src/images/categories/dark/Experimental.png\"\u003e\u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/newrelic/opensource-website/raw/main/src/images/categories/Experimental.png\"\u003e\u003cimg alt=\"New Relic Open Source experimental project banner.\" src=\"https://github.com/newrelic/opensource-website/raw/main/src/images/categories/Experimental.png\"\u003e\u003c/picture\u003e\u003c/a\u003e\n\n# New Relic's Elixir agent\n\n[![Build Status](https://github.com/newrelic/elixir_agent/workflows/CI/badge.svg)](https://github.com/newrelic/elixir_agent/actions?query=workflow%3ACI)\n[![Hex.pm Version](https://img.shields.io/hexpm/v/new_relic_agent.svg)](https://hex.pm/packages/new_relic_agent)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/new_relic_agent/)\n[![License](https://img.shields.io/badge/license-Apache%202-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nThe 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.\n\n[View the Documentation](https://hexdocs.pm/new_relic_agent)\n\n### Support Statement\n\nNew 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](https://forum.newrelic.com/s/).\n\n### Contributing\n\nWe 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](mailto:opensource@newrelic.com).\n\nA 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.\n\nIf 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.\n\n### License\nThe open-source Elixir agent is licensed under the Apache 2.0 License.\n\n## Installation\n\nInstall the [Hex package](https://hex.pm/packages/new_relic_agent)\n\nRequirements:\n* Erlang/OTP 24\n* Elixir 1.11\n\n```elixir\ndefp deps do\n  [\n    {:new_relic_agent, \"~\u003e 1.0\"}\n  ]\nend\n```\n\nIf using an Elixir version before 1.18.x, please also add `:jason` to your dependency list.\n\n```elixir\n{:jason, \"~\u003e 1.0\"}\n```\n\n## Configuration\n\nYou need to set two required configuration keys so we can authenticate properly.\n\n#### Via Application config\n\n```elixir\nconfig :new_relic_agent,\n  app_name: \"My App\",\n  license_key: \"license_key\"\n```\n\n#### Via Environment variables\n\nYou can also configure these attributes via `ENV` vars, which helps keep secrets out of source code.\n\n* `NEW_RELIC_APP_NAME`\n* `NEW_RELIC_LICENSE_KEY`\n\n## Telemetry-based auto-instrumentation\n\nSome common Elixir packages are auto-instrumented via [`telemetry`](https://github.com/beam-telemetry/telemetry)\n\n* [`Plug`](https://github.com/elixir-plug/plug): See [NewRelic.Telemetry.Plug](https://hexdocs.pm/new_relic_agent/NewRelic.Telemetry.Plug.html) for details.\n* [`Phoenix`](https://github.com/phoenixframework/phoenix): See [NewRelic.Telemetry.Phoenix](https://hexdocs.pm/new_relic_agent/NewRelic.Telemetry.Phoenix.html) for details.\n* [`Phoenix LiveView`](https://github.com/phoenixframework/phoenix_live_view): See [NewRelic.Telemetry.PhoenixLiveView](https://hexdocs.pm/new_relic_agent/NewRelic.Telemetry.PhoenixLiveView.html) for details.\n* [`Ecto`](https://github.com/elixir-ecto/ecto): See [NewRelic.Telemetry.Ecto](https://hexdocs.pm/new_relic_agent/NewRelic.Telemetry.Ecto.html) for details.\n* [`Redix`](https://github.com/whatyouhide/redix): See [NewRelic.Telemetry.Redix](https://hexdocs.pm/new_relic_agent/NewRelic.Telemetry.Redix.html) for details.\n* [`Finch`](https://github.com/sneako/finch): See [NewRelic.Telemetry.Finch](https://hexdocs.pm/new_relic_agent/NewRelic.Telemetry.Finch.html) for details.\n* [`Oban`](https://github.com/oban-bg/oban): See [NewRelic.Telemetry.Oban](https://hexdocs.pm/new_relic_agent/NewRelic.Telemetry.Oban.html) for details.\n* [`Absinthe`](https://github.com/absinthe-graphql/absinthe): See [NewRelic.Telemetry.Absinthe](https://hexdocs.pm/new_relic_agent/NewRelic.Telemetry.Absinthe.html) for details.\n\n## Opt-In agent features\n\nThere are a few advanced agent features that can be enabled via configuration. Please see the documentation for more information.\n\n* [Logs In Context](https://hexdocs.pm/new_relic_agent/NewRelic.Config.html#feature/1-logs-in-context) - See your logs in the context of the Transaction / Distributed Trace where they originated.\n* [Infinite Tracing](https://hexdocs.pm/new_relic_agent/NewRelic.Config.html#feature/1-infinite-tracing) - Use a New Relic Trace Observer to get tail based sampling of Distributed Traces.\n* [Security Controls](https://hexdocs.pm/new_relic_agent/NewRelic.Config.html#feature?/1-security)\n\n## Manual instrumentation\n\n#### Custom Transactions\n\nTransactions are the main unit of work reported to New Relic. `Plug` and `Phoenix` instrumentation automatically report a Web Transaction for each request. `Oban` instrumentation reports an \"Other\" Transaction for each job. \n\nYou may start an Custom \"Other\" Transaction for work outside auto-instrumented systems. This could used be while consuming from a message queue, for example.\n\n```elixir\ndefmodule Worker do\n  use NewRelic.Tracer\n\n  def process_messages do\n    NewRelic.other_transaction(\"Worker\", \"ProcessMessages\") do\n      # ...\n    end\n  end\nend\n```\n\n#### Transaction propagation\n\nTransactions will propagate to any process spawned and linked (ex: `Task.async`), but will _not_ follow a process that isn't linked (ex: `Task.Supervisor.async_nolink`).\n\nIf you are using a `Task.Supervisor.async_nolink` to spawn work, you can use the pre-instrumented `NewRelic.Instrumented.Task` wrapper 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.\n\n```elixir\nalias NewRelic.Instrumented.Task\n\nTask.Supervisor.async_nolink(MyTaskSupervisor, fn -\u003e\n  # This process will be automatically connected to the current Transaction...\nend)\n```\n\nFor more fine grained control of Transaction propagation, check out the following functions:\n\n* `NewRelic.exclude_from_transaction/0`\n* `NewRelic.ignore_transaction/0`\n* `NewRelic.get_transaction/0`\n* `NewRelic.connect_to_transaction/1`\n* `NewRelic.disconnect_from_transaction/0`\n\n#### Function tracing\n\n`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.\n\n```elixir\ndefmodule MyModule do\n  use NewRelic.Tracer\n\n  @trace :work\n  def work do\n    # Will report as `MyModule.work/0`\n\n    NewRelic.add_span_attributes(some: \"attribute\")\n  end\nend\n```\n\nIf you want to trace a sub-set of a function, you can use the `NewRelic.span` macro.\n\n```elixir\ndefmodule MyModule do\n  use NewRelic.Tracer\n\n  def work do\n    # Do some stuff..\n\n    NewRelic.span \"do.some_work\", user_id: \"abc123\" do\n      # Span will report as `do.some_work` and have a `user_id` attribute\n      # Will return the result of the block\n    end\n  end\nend\n```\n\n#### Distributed Tracing\n\nIncoming Distributed Traces are automatically connected if incoming HTTP requests have trace headers. Requests to other services can be connected with an additional outgoing header.\n\n```elixir\ndefmodule MyExternalService do\n  def request(method, url, headers) do\n    headers = headers ++ NewRelic.distributed_trace_headers(:http)\n    HttpClient.request(method, url, headers)\n  end\nend\n```\n\n#### Mix Tasks\n\n`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.\n\n```elixir\ndefmodule Mix.Tasks.Example do\n  use Mix.Task\n  use NewRelic.Instrumented.Mix.Task\n\n  def run(args) do\n    # ...\n  end\nend\n```\n\n## Advanced configuration\n\n#### HTTP client settings\n\n`: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:\n\n```elixir\nconfig :new_relic_agent,\n  app_name: \"My App\",\n  license_key: \"license_key\",\n  httpc_request_options: [connect_timeout: 5000]\n```\n\n#### Ignore paths\n\nYou can configure some paths to be automatically ignored:\n\n```elixir\nconfig :new_relic_agent,\n  ignore_paths: [\n    \"/health\",\n    ~r/longpoll/\n  ]\n```\n\n#### Disabling\n\nIf you want to disable the agent, you can do it in two different ways:\n\n* Application config: `config :new_relic_agent, license_key: nil`\n* Environment variables: `NEW_RELIC_HARVEST_ENABLED=false`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewrelic%2Felixir_agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnewrelic%2Felixir_agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewrelic%2Felixir_agent/lists"}