defmodule NewRelic do
  @moduledoc """
  New Relic Agent - Public API
  """

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

  ```elixir
  NewRelic.set_transaction_name("/Plug/custom/transaction/name")
  ```
  """
  @spec set_transaction_name(String.t()) :: any()
  defdelegate set_transaction_name(name), to: NewRelic.Transaction.Reporter

  @doc """
  Report custom attributes on the current Transaction

  Reporting nested data structures is supported by auto-flattening them
  into a list of key-value pairs.

  ```elixir
  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
  """
  @spec add_attributes(attributes :: Keyword.t()) :: any()
  defdelegate add_attributes(attributes), to: NewRelic.Transaction.Reporter

  @doc false
  @spec incr_attributes(attributes :: Keyword.t()) :: any()
  defdelegate incr_attributes(attributes), to: NewRelic.Transaction.Reporter

  @doc """
  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

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

  > #### Warning {: .error}
  >
  > * You can't start a new transaction within an existing one. Any process
  > spawned inside a transaction belongs to that transaction.
  > * Do _not_ use this for processes that live a very long time, doing so
  > will risk increased memory growth tracking attributes in the transaction!

  ## 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()) :: any()
  defdelegate start_transaction(category, name), to: NewRelic.OtherTransaction

  @spec start_transaction(String.t(), String.t(), headers :: map) :: any()
  defdelegate start_transaction(category, name, headers), to: NewRelic.OtherTransaction

  @doc """
  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.
  """
  @spec stop_transaction() :: any()
  defdelegate stop_transaction(), to: NewRelic.OtherTransaction

  @doc """
  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

  ```elixir
  defmodule Worker do
    use NewRelic.Tracer

    def process_messages do
      NewRelic.other_transaction("Worker", "ProcessMessages") do
        # ...
      end
    end
  end
  ```
  """
  defmacro other_transaction(category, name, do: block) do
    quote do
      NewRelic.start_transaction(unquote(category), unquote(name))
      res = unquote(block)
      NewRelic.stop_transaction()
      res
    end
  end

  defmacro other_transaction(category, name, headers, do: block) do
    quote do
      NewRelic.start_transaction(unquote(category), unquote(name), unquote(headers))
      res = unquote(block)
      NewRelic.stop_transaction()
      res
    end
  end

  @doc """
  Call within a transaction to prevent it from reporting.

  ## Example

  ```elixir
  def index(conn, _) do
    NewRelic.ignore_transaction()
    send_resp(conn, 200, "Health check OK")
  end
  ```
  """
  @spec ignore_transaction() :: any()
  defdelegate ignore_transaction(), to: NewRelic.Transaction.Reporter

  @doc """
  Call to exclude the current process from being part of the Transaction.
  """
  @spec exclude_from_transaction() :: any()
  defdelegate exclude_from_transaction(), to: NewRelic.Transaction.Reporter

  @doc """
  Advanced:
  Return a Transaction reference that can be used to manually connect a
  process to a Transaction with `NewRelic.connect_to_transaction/1`
  """
  @type tx_ref :: any()
  @spec get_transaction() :: tx_ref
  defdelegate get_transaction(), to: NewRelic.Transaction.Reporter

  @doc """
  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.
  """
  @spec connect_to_transaction(tx_ref) :: any()
  defdelegate connect_to_transaction(ref), to: NewRelic.Transaction.Reporter

  @doc """
  Advanced:
  Call to manually disconnect the current process from the current Transaction.
  """
  @spec disconnect_from_transaction() :: any()
  defdelegate disconnect_from_transaction(), to: NewRelic.Transaction.Reporter

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

  ## Examples

  ```elixir
  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)
  ```
  """
  @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()
  defdelegate set_span(type, attributes), to: NewRelic.DistributedTrace

  @doc """
  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

  ```elixir
  NewRelic.add_span_attributes(some: "attribute")
  ```
  """
  @spec add_span_attributes(attributes :: Keyword.t()) :: any()
  defdelegate add_span_attributes(attributes), to: NewRelic.DistributedTrace

  @doc """
  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:

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

  ## Notes

  * Call `distributed_trace_headers` immediately before making the
  request since calling the function marks the "start" time of the request.
  """
  @spec distributed_trace_headers(:http) :: [{key :: String.t(), value :: String.t()}]
  @spec distributed_trace_headers(:other) :: map()
  defdelegate distributed_trace_headers(type), to: NewRelic.DistributedTrace

  @type name :: String.t() | {primary_name :: String.t(), secondary_name :: String.t()}

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

  ```elixir
  NewRelic.span("do.some_work", user_id: "abc123") do
    # do some work
  end
  ```

  Note: You can also use `@trace` annotations to instrument functions without modifying code.
  """
  @spec span(name :: name, attributes :: Keyword.t()) :: term()
  defmacro span(name, attributes \\ [], do: block) do
    quote do
      id = make_ref()
      NewRelic.Tracer.Direct.start_span(id, unquote(name), attributes: unquote(attributes))
      res = unquote(block)
      NewRelic.Tracer.Direct.stop_span(id)
      res
    end
  end

  @doc """
  See: `NewRelic.distributed_trace_headers/1`
  """
  @deprecated "Use distributed_trace_headers instead"
  defdelegate create_distributed_trace_payload(type),
    to: NewRelic.DistributedTrace,
    as: :distributed_trace_headers

  @doc """
  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:

  ```elixir
  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`
  """
  @spec sample_process() :: any()
  defdelegate sample_process, to: NewRelic.Sampler.Process

  @doc """
  Report a Custom event to NRDB.

  ## Example

  ```elixir
  NewRelic.report_custom_event("EventType", %{"foo" => "bar"})
  ```
  """
  @spec report_custom_event(type :: String.t(), event :: map()) :: any()
  defdelegate report_custom_event(type, event),
    to: NewRelic.Harvest.Collector.CustomEvent.Harvester

  @doc """
  Report a Dimensional Metric.

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

  ## Example

  ```elixir
  NewRelic.report_dimensional_metric(:count, "my_metric_name", 1, %{some: "attributes"})
  ```
  """
  @spec report_dimensional_metric(
          type :: :count | :gauge | :summary,
          name :: String.t(),
          value :: number,
          attributes :: map()
        ) :: any()
  defdelegate report_dimensional_metric(type, name, value, attributes \\ %{}),
    to: NewRelic.Harvest.TelemetrySdk.DimensionalMetrics.Harvester

  @doc """
  Report a Custom metric.

  ## Example

  ```elixir
  NewRelic.report_custom_metric("My/Metric", 123)
  ```
  """
  @spec report_custom_event(name :: String.t(), value :: number()) :: any()
  defdelegate report_custom_metric(name, value),
    to: NewRelic.Harvest.Collector.Metric.Harvester

  @doc """
  Increment a Custom metric.

  ## Example

  ```elixir
  NewRelic.increment_custom_metric("My/Metric")
  ```
  """
  @spec increment_custom_metric(name :: String.t(), count :: integer()) :: any()
  defdelegate increment_custom_metric(name, count \\ 1),
    to: NewRelic.Harvest.Collector.Metric.Harvester

  @doc """
  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

  ```elixir
  try do
    raise RuntimeError
  rescue
    exception -> NewRelic.notice_error(exception, __STACKTRACE__)
  end
  ```
  """
  @spec notice_error(Exception.t(), Exception.stacktrace()) :: any()
  defdelegate notice_error(exception, stacktrace), to: NewRelic.Transaction.Reporter

  @doc false
  defdelegate enable_erlang_trace, to: NewRelic.Transaction.ErlangTraceManager

  @doc false
  defdelegate disable_erlang_trace, to: NewRelic.Transaction.ErlangTraceManager

  @doc false
  defdelegate report_aggregate(meta, values), to: NewRelic.Aggregate.Reporter

  @doc false
  defdelegate report_sample(category, values), to: NewRelic.Sampler.Reporter

  @doc false
  defdelegate report_span(span), to: NewRelic.Span.Reporter

  @doc false
  defdelegate report_metric(identifier, values), to: NewRelic.Harvest.Collector.Metric.Harvester

  @doc false
  defdelegate log(level, message), to: NewRelic.Logger

  @doc false
  defdelegate manual_shutdown(), to: NewRelic.Harvest.Supervisor
end