README.md

SpandexEcto

Tools for integrating Ecto with Spandex.

Limitations

Due to some recent changes in Ecto, we can no longer effectively trace the execution of parallel preloads. All other queries work fine, but until we figure something out that leverages either telemetry or until the task feature listed here is added to the language, we won't be able to support tracing parallel preloads.

Installation

Add spandex_ecto to your list of dependencies in mix.exs:

def deps do
  [
    {:spandex_ecto, "~> 0.7"}
  ]
end

Configuration

Configure SpandexEcto globally in your application config:

# config/config.exs

config :spandex_ecto, SpandexEcto.EctoLogger,
  service: :ecto, # Optional
  tracer: MyApp.Tracer, # Required

Then attach it to your repository's telemetry events:

# lib/my_app/application.ex

:ok = :telemetry.attach(
  "spandex-query-tracer",
  # this should match your repo's telemetry prefix
  [:my_app, :repo, :query],
  &SpandexEcto.TelemetryAdapter.handle_event/4,
  nil
)

You can override the global configuration by passing overrides to :telemetry.attach/4 (useful for projects with multiple Ecto repos):

# lib/my_app/application.ex

:ok = :telemetry.attach(
  "spandex-query-tracer-other-repo",
  [:my_app, :other_repo, :query],
  &SpandexEcto.TelemetryAdapter.handle_event/4,
  # this config will override the global config
  service: :other_db,
  tracer: MyApp.OtherRepoTracer
)

NOTE: If you are upgrading from Ecto 2, make sure to remove the loggers entry from your configuration after adding :telemetry.attach/4.

Options

The following configuration options are supported:

Option	Description	Default
tracer	Tracer instance to use for reporting traces (required)
service	Service name for Ecto traces	ecto
truncate	Maximum length of a query (excess will be truncated)	5000

Ecto 2

To integrate SpandexEcto with pre-:telemetry versions of Ecto you need to add SpandexEcto.EctoLogger as a logger to your repository.

Be aware that this is a compile time configuration. As such, if you change this you may need to mix compile --force and/or mix deps.compile --force ecto.

# config/config.exs

config :my_app, MyApp.Repo,
  loggers: [
    {Ecto.LogEntry, :log, [:info]},
    {SpandexEcto.EctoLogger, :trace, ["database_name"]}
  ]

Customizing Span Resources

By default, SpandexEcto uses the query as name for the span's resource. In order get a better feeling for the context of your spans, you can label your span's resources using the option :telemetry_options of almost all of Ecto.Repo's repository functions.

Examples

Repo.all(query, telemetry_options: [spandex_resource: "users-with-addresses"])
Repo.get!(User, id, telemetry_options: [spandex_resource: "get-user"])