Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <memory>
       4             : #include <string>
       5             : #include <vector>
       6             : 
       7             : #include "envoy/common/pure.h"
       8             : #include "envoy/stream_info/stream_info.h"
       9             : #include "envoy/tracing/trace_config.h"
      10             : 
      11             : namespace Envoy {
      12             : namespace Tracing {
      13             : 
      14             : class Span;
      15             : using SpanPtr = std::unique_ptr<Span>;
      16             : 
      17             : /**
      18             :  * Basic abstraction for span.
      19             :  */
      20             : class Span {
      21             : public:
      22          97 :   virtual ~Span() = default;
      23             : 
      24             :   /**
      25             :    * Set the operation name.
      26             :    * @param operation the operation name
      27             :    */
      28             :   virtual void setOperation(absl::string_view operation) PURE;
      29             : 
      30             :   /**
      31             :    * Attach metadata to a Span, to be handled in an implementation-dependent fashion.
      32             :    * @param name the name of the tag
      33             :    * @param value the value to associate with the tag
      34             :    */
      35             :   virtual void setTag(absl::string_view name, absl::string_view value) PURE;
      36             : 
      37             :   /**
      38             :    * Record an event associated with a span, to be handled in an implementation-dependent fashion.
      39             :    * @param timestamp the time of the event.
      40             :    * @param event the name of the event.
      41             :    */
      42             :   virtual void log(SystemTime timestamp, const std::string& event) PURE;
      43             : 
      44             :   /**
      45             :    * Capture the final duration for this Span and carry out any work necessary to complete it.
      46             :    * Once this method is called, the Span may be safely discarded.
      47             :    */
      48             :   virtual void finishSpan() PURE;
      49             : 
      50             :   /**
      51             :    * Mutate the provided headers with the context necessary to propagate this
      52             :    * (implementation-specific) trace.
      53             :    * @param request_headers the headers to which propagation context will be added
      54             :    * @param upstream connecting host description
      55             :    */
      56             :   virtual void injectContext(TraceContext& trace_conext,
      57             :                              const Upstream::HostDescriptionConstSharedPtr& upstream) PURE;
      58             : 
      59             :   /**
      60             :    * Create and start a child Span, with this Span as its parent in the trace.
      61             :    * @param config the tracing configuration
      62             :    * @param name operation name captured by the spawned child
      63             :    * @param start_time initial start time for the operation captured by the child
      64             :    */
      65             :   virtual SpanPtr spawnChild(const Config& config, const std::string& name,
      66             :                              SystemTime start_time) PURE;
      67             : 
      68             :   /**
      69             :    * This method overrides any previous sampling decision associated with the trace instance.
      70             :    * If the sampled parameter is false, this span and any subsequent child spans
      71             :    * are not reported to the tracing system.
      72             :    * @param sampled whether the span and any subsequent child spans should be sampled
      73             :    */
      74             :   virtual void setSampled(bool sampled) PURE;
      75             : 
      76             :   /**
      77             :    * Retrieve a key's value from the span's baggage.
      78             :    * This baggage data could've been set by this span or any parent spans.
      79             :    * @param key baggage key
      80             :    * @return the baggage's value for the given input key
      81             :    */
      82             :   virtual std::string getBaggage(absl::string_view key) PURE;
      83             : 
      84             :   /**
      85             :    * Set a key/value pair in the current span's baggage.
      86             :    * All subsequent child spans will have access to this baggage.
      87             :    * @param key baggage key
      88             :    * @param key baggage value
      89             :    */
      90             :   virtual void setBaggage(absl::string_view key, absl::string_view value) PURE;
      91             : 
      92             :   /**
      93             :    * Retrieve the trace ID associated with this span.
      94             :    * The trace id may be generated for this span, propagated by parent spans, or
      95             :    * not created yet.
      96             :    * @return trace ID as a hex string
      97             :    */
      98             :   virtual std::string getTraceIdAsHex() const PURE;
      99             : };
     100             : 
     101             : /**
     102             :  * Tracing driver is responsible for span creation.
     103             :  */
     104             : class Driver {
     105             : public:
     106           0 :   virtual ~Driver() = default;
     107             : 
     108             :   /**
     109             :    * Start driver specific span.
     110             :    */
     111             :   virtual SpanPtr startSpan(const Config& config, TraceContext& trace_context,
     112             :                             const StreamInfo::StreamInfo& stream_info,
     113             :                             const std::string& operation_name,
     114             :                             Tracing::Decision tracing_decision) PURE;
     115             : };
     116             : 
     117             : using DriverPtr = std::unique_ptr<Driver>;
     118             : using DriverSharedPtr = std::shared_ptr<Driver>;
     119             : 
     120             : } // namespace Tracing
     121             : } // namespace Envoy