Line data    Source code

       1             : #pragma once
       2             : 
       3             : // This component provides a struct, `TracerConfig`, used to configure a
       4             : // `Tracer`.  `Tracer` is instantiated with a `FinalizedTracerConfig`, which
       5             : // must be obtained from the result of a call to `finalize_config`.
       6             : 
       7             : #include <cstddef>
       8             : #include <memory>
       9             : #include <variant>
      10             : #include <vector>
      11             : 
      12             : #include "clock.h"
      13             : #include "datadog_agent_config.h"
      14             : #include "error.h"
      15             : #include "expected.h"
      16             : #include "propagation_style.h"
      17             : #include "runtime_id.h"
      18             : #include "span_defaults.h"
      19             : #include "span_sampler_config.h"
      20             : #include "trace_sampler_config.h"
      21             : 
      22             : namespace datadog {
      23             : namespace tracing {
      24             : 
      25             : class Collector;
      26             : class Logger;
      27             : class SpanSampler;
      28             : class TraceSampler;
      29             : 
      30             : struct TracerConfig {
      31             :   // `defaults` are properties that spans created by the tracer will have unless
      32             :   // overridden at the time of their creation.  See `span_defaults.h`.  Note
      33             :   // that `defaults.service` is required to have a nonempty value.
      34             :   SpanDefaults defaults;
      35             : 
      36             :   // `agent` configures a `DatadogAgent` collector instance.  See
      37             :   // `datadog_agent_config.h`.  Note that `agent` is ignored if `collector` is
      38             :   // set or if `report_traces` is `false`.
      39             :   DatadogAgentConfig agent;
      40             : 
      41             :   // `collector` is a `Collector` instance that the tracer will use to report
      42             :   // traces to Datadog.  If `collector` is null, then a `DatadogAgent` instance
      43             :   // will be created using the `agent` configuration.  Note that `collector` is
      44             :   // ignored if `report_traces` is `false`.
      45             :   std::shared_ptr<Collector> collector = nullptr;
      46             : 
      47             :   // `report_traces` indicates whether traces generated by the tracer will be
      48             :   // sent to a collector (`true`) or discarded on completion (`false`).  If
      49             :   // `report_traces` is `false`, then both `agent` and `collector` are ignored.
      50             :   // `report_traces` is overridden by the `DD_TRACE_ENABLED` environment
      51             :   // variable.
      52             :   bool report_traces = true;
      53             : 
      54             :   // `report_telemetry` indicates whether telemetry about the tracer will be
      55             :   // sent to a collector (`true`) or discarded on completion (`false`).  If
      56             :   // `report_telemetry` is `false`, then this feature is disabled.
      57             :   // `report_telemetry` is overridden by the
      58             :   // `DD_INSTRUMENTATION_TELEMETRY_ENABLED` environment variable.
      59             :   bool report_telemetry = true;
      60             : 
      61             :   // `trace_sampler` configures trace sampling.  Trace sampling determines which
      62             :   // traces are sent to Datadog.  See `trace_sampler_config.h`.
      63             :   TraceSamplerConfig trace_sampler;
      64             : 
      65             :   // `span_sampler` configures span sampling.  Span sampling allows specified
      66             :   // spans to be sent to Datadog even when their enclosing trace is dropped by
      67             :   // the trace sampler.  See `span_sampler_config.h`.
      68             :   SpanSamplerConfig span_sampler;
      69             : 
      70             :   // `injection_styles` indicates with which tracing systems trace propagation
      71             :   // will be compatible when injecting (sending) trace context.
      72             :   // All styles indicated by `injection_styles` are used for injection.
      73             :   // `injection_styles` is overridden by the `DD_TRACE_PROPAGATION_STYLE_INJECT`
      74             :   // and `DD_TRACE_PROPAGATION_STYLE` environment variables.
      75             :   std::vector<PropagationStyle> injection_styles = {PropagationStyle::DATADOG,
      76             :                                                     PropagationStyle::W3C};
      77             : 
      78             :   // `extraction_styles` indicates with which tracing systems trace propagation
      79             :   // will be compatible when extracting (receiving) trace context.
      80             :   // Extraction styles are applied in the order in which they appear in
      81             :   // `extraction_styles`. The first style that produces trace context or
      82             :   // produces an error determines the result of extraction.
      83             :   // `extraction_styles` is overridden by the
      84             :   // `DD_TRACE_PROPAGATION_STYLE_EXTRACT` and `DD_TRACE_PROPAGATION_STYLE`
      85             :   // environment variables.
      86             :   std::vector<PropagationStyle> extraction_styles = {PropagationStyle::DATADOG,
      87             :                                                      PropagationStyle::W3C};
      88             : 
      89             :   // `report_hostname` indicates whether the tracer will include the result of
      90             :   // `gethostname` with traces sent to the collector.
      91             :   bool report_hostname = false;
      92             : 
      93             :   // `tags_header_size` is the maximum allowed size, in bytes, of the serialized
      94             :   // value of the "X-Datadog-Tags" header used when injecting trace context for
      95             :   // propagation.  If the serialized value of the header would exceed
      96             :   // `tags_header_size`, the header will be omitted instead.
      97             :   std::size_t tags_header_size = 512;
      98             : 
      99             :   // `logger` specifies how the tracer will issue diagnostic messages.  If
     100             :   // `logger` is null, then it defaults to a logger that inserts into
     101             :   // `std::cerr`.
     102             :   std::shared_ptr<Logger> logger = nullptr;
     103             : 
     104             :   // `log_on_startup` indicates whether the tracer will log a banner of
     105             :   // configuration information once initialized.
     106             :   // `log_on_startup` is overridden by the `DD_TRACE_STARTUP_LOGS` environment
     107             :   // variable.
     108             :   bool log_on_startup = true;
     109             : 
     110             :   // `trace_id_128_bit` indicates whether the tracer will generate 128-bit trace
     111             :   // IDs.  If true, the tracer will generate 128-bit trace IDs. If false, the
     112             :   // tracer will generate 64-bit trace IDs. `trace_id_128_bit` is overridden by
     113             :   // the `DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED` environment variable.
     114             :   bool trace_id_128_bit = true;
     115             : 
     116             :   // `runtime_id` denotes the current run of the application in which the tracer
     117             :   // is embedded. If `runtime_id` is not specified, then it defaults to a
     118             :   // pseudo-randomly generated value. A server that contains multiple tracers,
     119             :   // such as those in the worker threads/processes of a reverse proxy, might
     120             :   // specify the same `runtime_id` for all tracer instances in the same run.
     121             :   Optional<RuntimeID> runtime_id;
     122             : };
     123             : 
     124             : // `FinalizedTracerConfig` contains `Tracer` implementation details derived from
     125             : // a valid `TracerConfig` and accompanying environment.
     126             : // `FinalizedTracerConfig` must be obtained by calling `finalize_config`.
     127             : class FinalizedTracerConfig {
     128             :   friend Expected<FinalizedTracerConfig> finalize_config(
     129             :       const TracerConfig& config, const Clock& clock);
     130         796 :   FinalizedTracerConfig() = default;
     131             : 
     132             :  public:
     133             :   SpanDefaults defaults;
     134             : 
     135             :   std::variant<std::monostate, FinalizedDatadogAgentConfig,
     136             :                std::shared_ptr<Collector>>
     137             :       collector;
     138             : 
     139             :   FinalizedTraceSamplerConfig trace_sampler;
     140             :   FinalizedSpanSamplerConfig span_sampler;
     141             : 
     142             :   std::vector<PropagationStyle> injection_styles;
     143             :   std::vector<PropagationStyle> extraction_styles;
     144             : 
     145             :   bool report_hostname;
     146             :   std::size_t tags_header_size;
     147             :   std::shared_ptr<Logger> logger;
     148             :   bool log_on_startup;
     149             :   bool trace_id_128_bit;
     150             :   bool report_telemetry;
     151             :   Optional<RuntimeID> runtime_id;
     152             :   Clock clock;
     153             : };
     154             : 
     155             : // Return a `FinalizedTracerConfig` from the specified `config` and from any
     156             : // relevant environment variables.  If any configuration is invalid, return an
     157             : // `Error`.
     158             : // Optionally specify a `clock` used to calculate span start times, span
     159             : // durations, and timeouts.  If `clock` is not specified, then `default_clock`
     160             : // is used.
     161             : Expected<FinalizedTracerConfig> finalize_config(const TracerConfig& config);
     162             : Expected<FinalizedTracerConfig> finalize_config(const TracerConfig& config,
     163             :                                                 const Clock& clock);
     164             : 
     165             : }  // namespace tracing
     166             : }  // namespace datadog