diff --git a/lib/quantum.ex b/lib/quantum.ex index 8478dfe..baae10c 100644 --- a/lib/quantum.ex +++ b/lib/quantum.ex @@ -1,4 +1,51 @@ defmodule Quantum do + use TelemetryRegistry + + telemetry_event(%{ + event: [:quantum, :job, :add], + description: "dispatched when a job is added", + measurements: "%{}", + metadata: "%{job: Quantum.Job.t(), scheduler: atom()}" + }) + + telemetry_event(%{ + event: [:quantum, :job, :update], + description: "dispatched when a job is updated", + measurements: "%{}", + metadata: "%{job: Quantum.Job.t(), scheduler: atom()}" + }) + + telemetry_event(%{ + event: [:quantum, :job, :delete], + description: "dispatched when a job is deleted", + measurements: "%{}", + metadata: "%{job: Quantum.Job.t(), scheduler: atom()}" + }) + + telemetry_event(%{ + event: [:quantum, :job, :start], + description: "dispatched on job execution start", + measurements: "%{system_time: integer()}", + metadata: + "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom()}" + }) + + telemetry_event(%{ + event: [:quantum, :job, :stop], + description: "dispatched on job execution end", + measurements: "%{duration: integer()}", + metadata: + "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), result: term()}" + }) + + telemetry_event(%{ + event: [:quantum, :job, :exception], + description: "dispatched on job execution fail", + measurements: "%{duration: integer()}", + metadata: + "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), kind: :throw | :error | :exit, reason: term(), stacktrace: list()}" + }) + @moduledoc """ Defines a quantum Scheduler. @@ -70,6 +117,55 @@ defmodule Quantum do * `:timezone` - Default timezone of new Job + ## Telemetry + + #{telemetry_docs()} + + ### Examples + + iex(1)> :telemetry_registry.discover_all(:quantum) + :ok + iex(2)> :telemetry_registry.spannable_events() + [{[:quantum, :job], [:start, :stop, :exception]}] + iex(3)> :telemetry_registry.list_events + [ + {[:quantum, :job, :add], Quantum, + %{ + description: "dispatched when a job is added", + measurements: "%{}", + metadata: "%{job: Quantum.Job.t(), scheduler: atom()}" + }}, + {[:quantum, :job, :delete], Quantum, + %{ + description: "dispatched when a job is deleted", + measurements: "%{}", + metadata: "%{job: Quantum.Job.t(), scheduler: atom()}" + }}, + {[:quantum, :job, :exception], Quantum, + %{ + description: "dispatched on job execution fail", + measurements: "%{duration: integer()}", + metadata: "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), kind: :throw | :error | :exit, reason: term(), stacktrace: list()}" + }}, + {[:quantum, :job, :start], Quantum, + %{ + description: "dispatched on job execution start", + measurements: "%{system_time: integer()}", + metadata: "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom()}" + }}, + {[:quantum, :job, :stop], Quantum, + %{ + description: "dispatched on job execution end", + measurements: "%{duration: integer()}", + metadata: "%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), result: term()}" + }}, + {[:quantum, :job, :update], Quantum, + %{ + description: "dispatched when a job is updated", + measurements: "%{}", + metadata: "%{job: Quantum.Job.t(), scheduler: atom()}" + }} + ] """ require Logger diff --git a/mix.exs b/mix.exs index 9344555..7ef89f0 100644 --- a/mix.exs +++ b/mix.exs @@ -76,8 +76,7 @@ defmodule Quantum.Mixfile do "pages/configuration.md", "pages/runtime-configuration.md", "pages/crontab-format.md", - "pages/run-strategies.md", - "pages/telemetry.md" + "pages/run-strategies.md" ], groups_for_modules: [ "Run Strategy": [ @@ -104,7 +103,8 @@ defmodule Quantum.Mixfile do {:ex_doc, ">= 0.0.0", only: [:dev, :docs], runtime: false}, {:excoveralls, "~> 0.5", only: [:test], runtime: false}, {:dialyxir, "~> 1.0-rc", only: [:dev], runtime: false}, - {:credo, "~> 1.0", only: [:dev], runtime: false} + {:credo, "~> 1.0", only: [:dev], runtime: false}, + {:telemetry_registry, "~> 0.2"} ] end end diff --git a/pages/telemetry.md b/pages/telemetry.md deleted file mode 100644 index 6dac35e..0000000 --- a/pages/telemetry.md +++ /dev/null @@ -1,57 +0,0 @@ -# Telemetry - -Since version [`3.2.0`](https://github.com/quantum-elixir/quantum-core/releases/tag/v3.2.0) `quantum` supports [`:telemetry`](https://hexdocs.pm/telemetry) metrics. - - - -## Overview - -The [`:telemetry`](https://hexdocs.pm/telemetry) library allows you to emit events at various stages of an application's lifecycle. You can then respond to these events by, among other things, aggregating them as metrics and sending the metrics data to a reporting destination. - -Telemetry stores events by their name in an ETS table, along with the handler for each event. Then, when a given event is executed, Telemetry looks up its handler and invokes it. - -## Telemetry Events - -Many Elixir libraries (including Quantum) are already using -the [`:telemetry`](http://hexdocs.pm/telemetry) package as a -way to give users more insight into the behavior of their -applications, by emitting events at key moments in the -application lifecycle. - -A Telemetry event is made up of the following: - - * `name` - A string (e.g. `"my_app.worker.stop"`) or a - list of atoms that uniquely identifies the event. - - * `measurements` - A map of atom keys (e.g. `:duration`) - and numeric values. - - * `metadata` - A map of key/value pairs that can be used - for tagging metrics. - -### Quantum Telemetry Events - -The following events are published by Quantum with the following measurements and metadata: - -* `[:quantum, :job]` - A span generated by `:telemetry.span/3` around the execution of a job - * `[:quantum, :job, :start]` - dispatched on job execution start - * Measurement: `%{system_time: native_time}` - * Metadata: `%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom()}` - * `[:quantum, :job, :exception]` - dispatched on job execution fail - * Measurement: `%{duration: native_time}` - * Metadata: `%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), kind: :throw | :error | :exit, reason: term(), stacktrace: list()}` - * `[:quantum, :job, :stop]` - dispatched on job execution end - * Measurement: `%{duration: native_time}` - * Metadata: `%{telemetry_span_context: term(), job: Quantum.Job.t(), node: Node.t(), scheduler: atom(), result: term()}` -* `[:quantum, :job, :add]` - dispatched when a job is added - * Measurement: `%{}` - * Metadata: `%{job: Quantum.Job.t(), scheduler: atom()}` -* `[:quantum, :job, :update]` - dispatched when a job is updated - * Measurement: `%{}` - * Metadata: `%{job: Quantum.Job.t(), scheduler: atom()}` -* `[:quantum, :job, :delete]` - dispatched when a job is deleted - * Measurement: `%{}` - * Metadata: `%{job: Quantum.Job.t(), scheduler: atom()}` diff --git a/test/quantum_test.exs b/test/quantum_test.exs new file mode 100644 index 0000000..0ce66ff --- /dev/null +++ b/test/quantum_test.exs @@ -0,0 +1,4 @@ +defmodule QuantumTest do + use ExUnit.Case + doctest Quantum +end