From f28fac31e2ddbe37d9273b53cfc8bdd360ebb2dd Mon Sep 17 00:00:00 2001 From: Greg Mefford Date: Thu, 30 Aug 2018 00:01:03 -0400 Subject: [PATCH 1/2] Support the deprecated Tracer.continue_trace/4 --- lib/tracer.ex | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/lib/tracer.ex b/lib/tracer.ex index d2900ce..6c4ad8f 100644 --- a/lib/tracer.ex +++ b/lib/tracer.ex @@ -196,10 +196,21 @@ defmodule Spandex.Tracer do end @impl Spandex.Tracer - def continue_trace(span_name, span_context, opts \\ []) do + def continue_trace(span_name, span_context, opts \\ []) + def continue_trace(span_name, %SpanContext{} = span_context, opts) do Spandex.continue_trace(span_name, span_context, config(opts, @otp_app)) end + # This is just to get around the ambiguous defaults until we fully remove this API + def continue_trace(span_name, trace_id, span_id) do + continue_trace(span_name, trace_id, span_id, []) + end + + @deprecated "please use continue_trace/3 instead." + def continue_trace(span_name, trace_id, span_id, opts) do + continue_trace(span_name, %SpanContext{trace_id: trace_id, parent_id: span_id}, opts) + end + @impl Spandex.Tracer def continue_trace_from_span(span_name, span, opts \\ []) do Spandex.continue_trace_from_span(span_name, span, config(opts, @otp_app)) From 64a75a8b8fb45932257db0671b420c64cc2db6e8 Mon Sep 17 00:00:00 2001 From: Greg Mefford Date: Thu, 30 Aug 2018 00:16:59 -0400 Subject: [PATCH 2/2] Prepare for release 2.2.0 --- CHANGELOG.md | 29 ++++++++++++++++ README.md | 98 ++++++++++++++++++++++++++++++++++++++-------------- mix.exs | 4 +-- 3 files changed, 104 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 444896f..37ad258 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] - No unreleased changes currently. +## [2.2.0] + +### Added +- The `Spandex.Trace` struct now includes `priority` and `baggage` fields, to + support priority sampling of distributed traces and trace-level baggage, + respectively. More details about these concepts can be found in the + OpenTracing documentation. An updated version of the `spandex_datadog` + library will enable support for this feature in terms of the + `Spandex.Adapter` and `Sender` APIs. + +### Changed +- It is no longer required that you specify the `env` option. If not specified, + it will default to `nil`. This is useful, for example, for allowing the + Datadog trace collector configured default to be used. +- The `Spandex.Adapter.distributed_context/2` callback now expects a + `SpanContext` struct to be returned, rather than a `Map`. +- Similarly, the `Spandex.continue_trace` function now expects a `SpanContext` + struct rather than a separate `trace_id` and `span_id`. +- The sender API now calls the `send_trace` function, passing in a + `Spandex.Trace` struct, rather than passing a list of `Spandex.Span` structs. + This means that you need to update the `spandex_datadog` to a compatible + version. + +### Deprecated +- `Spandex.continue_trace/4` is deprecated in favor of + `Spandex.continue_trace/3` +- Similarly, `Tracer.continue_trace/4` is deprecated in favor of + `Tracer.continue_trace/3` + ## [2.1.0] It is recommended to reread the README, to see the upgrade guide and understand the changes. diff --git a/README.md b/README.md index 325279d..bc4a207 100644 --- a/README.md +++ b/README.md @@ -8,29 +8,36 @@ View the [documentation](https://hexdocs.pm/spandex) - ## 2.0 Upgrade Guide -This is datadog specific since thats the only adapter. +This is Datadog-specific since that's currently the only adapter. * Include the adapter as a dependency (see below). -* Replace any occurrences of `Spandex.Adapters.Datadog` with `SpandexDatadog.Adapter` in your code. -* Replace any occurences of `Spandex.Adapters.ApiSender` with `SpandexDatadog.ApiSender` in your code. +* Replace any occurrences of `Spandex.Adapters.Datadog` with + `SpandexDatadog.Adapter` in your code. +* Replace any occurences of `Spandex.Adapters.ApiSender` with + `SpandexDatadog.ApiSender` in your code. ## Adapters * [Datadog](https://github.com/spandex-project/spandex_datadog) -* Thats it so far! If you want another adapter it should be relatively easy to write! This library is in charge of handling the state management of spans, and the adapter is just in charge of generating certain values and ultimately sending the values to the service. +* Thats it so far! If you want another adapter, it should be relatively easy to + write! This library is in charge of handling the state management of spans, + and the adapter is just in charge of generating certain values and ultimately + sending the values to the service. ## Attention -This library could use some work! I've become unexpectedly busy lately, so I haven't had the time I thought I would to work on it. Any contributions, to things like sampling, strict mode, different storage strategies and the like would be greatly appreciated. +This library could use some work! I've become unexpectedly busy lately, so I +haven't had the time I thought I would to work on it. Any contributions, to +things like sampling, strict mode, different storage strategies and the like +would be greatly appreciated. ## Installation ```elixir def deps do - [{:spandex, "~> 2.1.0"}] + [{:spandex, "~> 2.2.0"}] end ``` @@ -57,16 +64,24 @@ config :my_app, MyApp.Tracer, Or at runtime, by calling `configure/1` (usually in your application's startup) ```elixir -MyApp.Tracer.configure(disabled?: Mix.env == :test) +MyApp.Tracer.configure(disabled?: Mix.env() == :test) ``` -For more information on tracer configuration, view the docs for `Spandex.Tracer`. There you will find the documentation for the opts schema. The entire configuration can also be passed into each function in your tracer to be overridden if desired. For example: +For more information on Tracer configuration, view the docs for +`Spandex.Tracer`. There you will find the documentation for the `opts` schema. +The entire configuration can also be passed into each function in your tracer +to be overridden if desired. For example: `MyApp.Tracer.start_span("span_name", service: :some_special_service)` -Your configuration and the configuration in your config files is merged together, to avoid needing to specify this config at all times. +Your configuration and the configuration in your config files are merged +together, to avoid needing to specify this config at all times. -To bypass the tracer pattern entirely, you can call directly into the functions in `Spandex`, like `Spandex.start_span("span_name", [adapter: Foo, service: :bar])` +To bypass the Tracer pattern entirely, you can call directly into the functions +in `Spandex`, like `Spandex.start_span("span_name", [adapter: Foo, service: +:bar])`. Note that in this case, you will need to specify all of the +configuration options in each call, because the Tracer is not managing the +defaults for you. ### Adapter specific configuration @@ -76,17 +91,22 @@ For adapter configuration, see the documentation for that adapter There are 3 plugs provided for usage w/ Phoenix: -* `Spandex.Plug.StartTrace` - See moduledocs for options. Goes as early in your pipeline as possible. -* `Spandex.Plug.AddContext` - See moduledocs for options. Either after the router, or inside a pipeline in the router. +* `Spandex.Plug.StartTrace` - See moduledocs for options. Goes as early in your + pipeline as possible. +* `Spandex.Plug.AddContext` - See moduledocs for options. Either after the + router, or inside a pipeline in the router. * `Spandex.Plug.EndTrace` - Must go *after* your router. ## Distributed Tracing -Individual adapters can support distributed tracing. See their documentation for more information. +Individual adapters can support distributed tracing. See their documentation +for more information. ## Logger metadata -In general, you'll probably want the current span_id and trace_id in your logs, so that you can find them in your tracing service. Make sure to add `span_id` and `trace_id` to logger_metadata +In general, you'll probably want the current span_id and trace_id in your logs, +so that you can find them in your tracing service. Make sure to add `span_id` +and `trace_id` to logger_metadata ```elixir config :logger, :console, @@ -95,7 +115,8 @@ config :logger, :console, ## General Usage -The nicest interface for working with spans is the `span` macro, illustrated in `span_me_also` below. +The nicest interface for working with spans is the `span` macro, illustrated in +`span_me_also` below. ```elixir defmodule ManuallyTraced do @@ -134,25 +155,52 @@ end ### Metadata -See the module documentation for `Spandex.Span` as well as the documentation for the structs -contained as keys for that struct. They illustrate the keys that are known to either be common -keys or to have UI sugar with certain clients. Its hard to find any kind of list of these published -anywhere, so let me know if you know of more! Examples +See the module documentation for `Spandex.Span` as well as the documentation +for the structs contained as keys for that struct. They illustrate the keys +that are known to either be common keys or to have UI sugar with certain +clients. Its hard to find any kind of list of these published anywhere, so let +me know if you know of more! + +For example: ```elixir -Spandex.update_span(type: :db, http: [url: "/posts", status_code: 400], sql_query: [query: "SELECT * FROM posts", rows: 10]) +Spandex.update_span( + type: :db, + http: [url: "/posts", status_code: 400], + sql_query: [query: "SELECT * FROM posts", rows: 10] +) ``` -Spandex used to ship with function decorators, but those decorators had a habit of causing weird compilation issues for certain users, and could be easily implemented by any user of the library. +Spandex used to ship with function decorators, but those decorators had a habit +of causing weird compilation issues for certain users, and could be easily +implemented by any user of the library. ## Asynchronous Processes -The current trace_id and span_id can be retrieved with `Tracer.current_trace_id()` and `Tracer.current_span_id()`. This can then be used as `Tracer.continue_trace("new_trace", trace_id, span_id)`. New spans can then be logged from there and will be sent in a separate batch. +The current `trace_id` and `span_id` can be retrieved and later used (for +example, from another process) as follows: + +```elixir +trace_id = Tracer.current_trace_id() +span_id = Tracer.current_span_id() +span_context = %SpanContext{trace_id: trace_id, parent_id: span_id} +Tracer.continue_trace("new_trace", span_context) +``` + +New spans can then be logged from there and sent in a separate batch. ## Strategies -There is (currently and temporarily) only one storage strategy, which can be changed via the `strategy` option. See tracer opt documentation for an example of setting it. To implement your own (ETS adapter should be on its way) simply implement the `Spandex.Strategy` behaviour. Keep in mind that the strategy is not an atomic pattern. It represents retrieving and wholesale replacing a trace, meaning that it is *not* safe to use across processes or concurrently. Each process should have its own store for its own generated spans. This should be fine because you can send multiple batches of spans for the same trace separately. +There is (currently and temporarily) only one storage strategy, which can be +changed via the `strategy` option. See Tracer opt documentation for an example +of setting it. To implement your own (ETS adapter should be on its way), simply +implement the `Spandex.Strategy` behaviour. Keep in mind that the strategy is +not an atomic pattern. It represents retrieving and wholesale replacing a +trace, meaning that it is *not* safe to use across processes or concurrently. +Each process should have its own store for its own generated spans. This should +be fine because you can send multiple batches of spans for the same trace +separately. ## Ecto Tracing -Check out [spandex_ecto](https://github.com/spandex-project/spandex_ecto) +Check out [spandex_ecto](https://github.com/spandex-project/spandex_ecto). diff --git a/mix.exs b/mix.exs index 627d948..3773cb1 100644 --- a/mix.exs +++ b/mix.exs @@ -4,7 +4,7 @@ defmodule Spandex.Mixfile do def project do [ app: :spandex, - version: "2.1.0", + version: "2.2.0", elixir: "~> 1.3", elixirc_paths: elixirc_paths(Mix.env()), build_embedded: Mix.env() == :prod, @@ -36,7 +36,7 @@ defmodule Spandex.Mixfile do # These are the default files included in the package [ name: :spandex, - maintainers: ["Zachary Daniel", "Andrew Summers"], + maintainers: ["Zachary Daniel", "Andrew Summers", "Greg Mefford"], licenses: ["MIT License"], links: %{"GitHub" => "https://github.com/zachdaniel/spandex"} ]