[DEVEX-2701]: Teleplug traces not showing up if traces are propagated from outside (#188)

Author: MaeIsBad

CHANGELOG.md

@@ -10,6 +10,14 @@ and this project adheres to
 
 ---
 
+## [2.1.0] - 2025-09-25
+
+### Added
+
+- `trace_propagation` configuration option, for specifying how traces should be propagated(`:as_parent`(default), `:as_link` and `disabled`)
+
+---
+
 ## [2.0.1] - 2025-08-04
 
 ### Fixed
@@ -78,7 +86,9 @@ and this project adheres to
   upgrade to OpenTelemetry API 1.1.0
 
 
-[Unreleased]: https://github.com/primait/teleplug/compare/2.0.1...HEAD
+
+[Unreleased]: https://github.com/primait/teleplug/compare/2.1.0...HEAD
+[2.1.0]: https://github.com/primait/teleplug/compare/2.0.1...2.1.0
 [2.0.1]: https://github.com/primait/teleplug/compare/2.0.0...2.0.1
 [2.0.0]: https://github.com/primait/teleplug/compare/1.1.3...2.0.0
 [1.1.3]: https://github.com/primait/teleplug/compare/1.1.2...1.1.3

README.md

@@ -30,9 +30,18 @@ be found at [https://hexdocs.pm/teleplug](https://hexdocs.pm/teleplug).
 In your pipeline add
 
 ```
-plug TelePlug
+plug Teleplug
 ```
 
+There are some options you can pass, for example
+
+```
+plug Teleplug,
+  trace_propagation: :as_link
+```
+
+see the module documentation for details
+
 ## Copyright and License
 
 Copyright (c) 2020 Prima.it

lib/teleplug.ex

@@ -42,21 +42,79 @@ defmodule Teleplug do
 
   defdelegate setup, to: Teleplug.Instrumentation
 
+  @typedoc """
+  Configuration options for Teleplug
+    * trace_propagation_opt(default: `:as_parent`) - configure how trace propagation works.
+  """
+  @type opts() :: [
+          trace_propagation: trace_propagation_opt()
+        ]
+
+  @typedoc "
+  How to handle trace propagation headers:
+   - `:as_parent` set the propagated trace span as a parent for the request handler span.
+    Note that if the parent span doesn't exist your trace might be dropped by the opentelemetry collector.
+    If that behaviour is undesirable(eg. when using a public endpoint) you should use the `:as_link` option.
+   - `:as_link` create a [link](https://opentelemetry.io/docs/concepts/signals/traces/#span-links) between the propagated span and the request handler span.
+   - `:disabled` disable trace propagation.
+  "
+  @type trace_propagation_opt() :: :as_parent | :as_link | :disabled
+
   @impl true
-  def init(opts), do: opts
+  @spec init(opts() | nil) :: opts()
+  def init(opts) when is_list(opts) do
+    # validate and set defaults for all options
+    {trace_propagation, opts} = Keyword.pop(opts, :trace_propagation, :as_parent)
+
+    if trace_propagation not in [:as_parent, :as_link, :disabled] do
+      raise ArgumentError,
+        message: "invalid trace_propagation configuration value: #{trace_propagation}"
+    end
+
+    unused_keys = Keyword.keys(opts)
+
+    if unused_keys != [] do
+      raise ArgumentError, message: "Unknown teleplug options: #{unused_keys}"
+    end
+
+    [
+      trace_propagation: trace_propagation
+    ]
+  end
+
+  def init(opts) when is_nil(opts), do: init([])
 
   @impl true
-  def call(conn, _opts) do
-    :otel_propagator_text_map.extract(conn.req_headers)
+  @spec call(Plug.Conn.t(), opts()) :: Plug.Conn.t()
+  def call(conn, opts) do
+    trace_propagation = Keyword.fetch!(opts, :trace_propagation)
 
     attributes =
       http_common_attributes(conn) ++
         http_server_attributes(conn) ++
         network_attributes(conn)
 
-    parent_ctx = Tracer.current_span_ctx()
+    if trace_propagation == :as_parent do
+      :otel_propagator_text_map.extract(conn.req_headers)
+    end
 
-    new_ctx = conn |> span_name() |> Tracer.start_span(%{kind: :server, attributes: attributes})
+    links =
+      case trace_propagation do
+        :as_link ->
+          OpenTelemetry.Ctx.new()
+          |> :otel_propagator_text_map.extract_to(conn.req_headers)
+          |> OpenTelemetry.Tracer.current_span_ctx()
+          |> OpenTelemetry.link()
+          |> List.wrap()
+
+        _ ->
+          []
+      end
+
+    new_ctx =
+      conn
+      |> span_name()
+      |> Tracer.start_span(%{kind: :server, attributes: attributes, links: links})
 
     Tracer.set_current_span(new_ctx)
 
@@ -74,7 +132,6 @@ defmodule Teleplug do
         RequestMonitor.end_span(request_monitor_ref)
       end
 
-      Tracer.set_current_span(parent_ctx)
       conn
     end)
   end

mix.exs

@@ -2,7 +2,7 @@ defmodule Teleplug.MixProject do
   use Mix.Project
 
   @source_url "https://github.com/primait/teleplug"
-  @version "2.0.1"
+  @version "2.1.0"
 
   def project do
     [

test/teleplug_test.exs

@@ -104,6 +104,70 @@ defmodule TeleplugTest do
            } = attributes
   end
 
+  test "trace propagation as parent by default" do
+    opts = Teleplug.init([])
+
+    {propagated_span_id, propagation_headers} =
+      Tracer.with_span "propagated" do
+        span_id =
+          OpenTelemetry.Tracer.current_span_ctx()
+          |> OpenTelemetry.Span.span_id()
+
+        headers = :otel_propagator_text_map.inject([])
+        {span_id, headers}
+      end
+
+    :get
+    |> conn("/")
+    |> Plug.Conn.merge_req_headers(propagation_headers)
+    |> Teleplug.call(opts)
+    |> Plug.Conn.send_resp(200, "ok")
+
+    assert_receive {:span, span(parent_span_id: ^propagated_span_id, name: "GET /")}, 1_000
+  end
+
+  test "trace propagation as link" do
+    opts = Teleplug.init(trace_propagation: :as_link)
+
+    {propagated_span_id, propagation_headers} =
+      Tracer.with_span "propagated" do
+        span_id =
+          OpenTelemetry.Tracer.current_span_ctx()
+          |> OpenTelemetry.Span.span_id()
+
+        headers = :otel_propagator_text_map.inject([])
+        {span_id, headers}
+      end
+
+    :get
+    |> conn("/")
+    |> Plug.Conn.merge_req_headers(propagation_headers)
+    |> Teleplug.call(opts)
+    |> Plug.Conn.send_resp(200, "ok")
+
+    assert_receive {:span, span(links: links, name: "GET /")}, 1_000
+    assert {:links, _, _, _, _, [link]} = links
+    assert {:link, _, ^propagated_span_id, _, _} = link
+  end
+
+  test "trace propagation disabled" do
+    opts = Teleplug.init(trace_propagation: :disabled)
+
+    propagation_headers =
+      Tracer.with_span "propagated" do
+        :otel_propagator_text_map.inject([])
+      end
+
+    :get
+    |> conn("/")
+    |> Plug.Conn.merge_req_headers(propagation_headers)
+    |> Teleplug.call(opts)
+    |> Plug.Conn.send_resp(200, "ok")
+
+    assert_receive {:span, span(parent_span_id: :undefined, links: links, name: "GET /")}, 1_000
+    assert {:links, _, _, _, _, []} = links
+  end
+
   def flush_mailbox do
     receive do
       _ -> flush_mailbox()