tracer_config.h

#pragma once

// This component provides a struct, `TracerConfig`, used to configure a
// `Tracer`.  `Tracer` is instantiated with a `FinalizedTracerConfig`, which
// must be obtained from the result of a call to `finalize_config`.

#include <datadog/telemetry/configuration.h>

#include <cstddef>
#include <memory>
#include <variant>
#include <vector>

#include "baggage.h"
#include "clock.h"
#include "datadog_agent_config.h"
#include "expected.h"
#include "http_endpoint_calculation_mode.h"
#include "propagation_style.h"
#include "runtime_id.h"
#include "span_defaults.h"
#include "span_sampler_config.h"
#include "trace_sampler_config.h"

namespace datadog {
namespace tracing {

class Collector;
class Logger;
class SpanSampler;
class TraceSampler;

struct TracerConfig {
  // Set the service name.
  //
  // Overriden by the `DD_SERVICE` environment variables.
  Optional<std::string> service;

  // Set the type of service.
  Optional<std::string> service_type;

  // Set the application environment.
  //
  // Overriden by the `DD_ENV` environment variable.
  // Example: `prod`, `pre-prod` or `staging`.
  Optional<std::string> environment;

  // Set the service version.
  //
  // Overriden by the `DD_VERSION` environment variable.
  // Example values: `1.2.3`, `6c44da20`, `2020.02.13`.
  Optional<std::string> version;

  // Set the default name for spans.
  Optional<std::string> name;

  // Set global tags to be attached to every span.
  //
  // Overriden by the `DD_TAGS` environment variable.
  Optional<std::unordered_map<std::string, std::string>> tags;

  // `agent` configures a `DatadogAgent` collector instance.  See
  // `datadog_agent_config.h`.  Note that `agent` is ignored if `collector` is
  // set or if `report_traces` is `false`.
  DatadogAgentConfig agent;

  // `collector` is a `Collector` instance that the tracer will use to report
  // traces to Datadog.  If `collector` is null, then a `DatadogAgent` instance
  // will be created using the `agent` configuration.  Note that `collector` is
  // ignored if `report_traces` is `false`.
  std::shared_ptr<Collector> collector;

  // `report_traces` indicates whether traces generated by the tracer will be
  // sent to a collector (`true`) or discarded on completion (`false`).  If
  // `report_traces` is `false`, then both `agent` and `collector` are ignored.
  // `report_traces` is overridden by the `DD_TRACE_ENABLED` environment
  // variable.
  Optional<bool> report_traces;

  // `telemetry` configures the telemetry module. See
  // `telemetry/configuration.h` By default, the telemetry module is enabled.
  telemetry::Configuration telemetry;

  // `trace_sampler` configures trace sampling.  Trace sampling determines which
  // traces are sent to Datadog.  See `trace_sampler_config.h`.
  TraceSamplerConfig trace_sampler;

  // `span_sampler` configures span sampling.  Span sampling allows specified
  // spans to be sent to Datadog even when their enclosing trace is dropped by
  // the trace sampler.  See `span_sampler_config.h`.
  SpanSamplerConfig span_sampler;

  // `injection_styles` indicates with which tracing systems trace propagation
  // will be compatible when injecting (sending) trace context.
  // All styles indicated by `injection_styles` are used for injection.
  // `injection_styles` is overridden by the `DD_TRACE_PROPAGATION_STYLE_INJECT`
  // and `DD_TRACE_PROPAGATION_STYLE` environment variables.
  Optional<std::vector<PropagationStyle>> injection_styles;

  // `extraction_styles` indicates with which tracing systems trace propagation
  // will be compatible when extracting (receiving) trace context.
  // Extraction styles are applied in the order in which they appear in
  // `extraction_styles`. The first style that produces trace context or
  // produces an error determines the result of extraction.
  // `extraction_styles` is overridden by the
  // `DD_TRACE_PROPAGATION_STYLE_EXTRACT` and `DD_TRACE_PROPAGATION_STYLE`
  // environment variables.
  Optional<std::vector<PropagationStyle>> extraction_styles;

  // `report_hostname` indicates whether the tracer will include the result of
  // `gethostname` with traces sent to the collector.
  Optional<bool> report_hostname;

  // `max_tags_header_size` is the maximum allowed size, in bytes, of the
  // serialized value of the "X-Datadog-Tags" header used when injecting trace
  // context for propagation.  If the serialized value of the header would
  // exceed `tags_header_size`, the header will be omitted instead.
  Optional<std::size_t> max_tags_header_size;

  // `logger` specifies how the tracer will issue diagnostic messages.  If
  // `logger` is null, then it defaults to no logging (`NullLogger`).  See
  // `CerrLogger` for an alternative.
  std::shared_ptr<Logger> logger;

  // `log_on_startup` indicates whether the tracer will log a banner of
  // configuration information once initialized.
  // `log_on_startup` is overridden by the `DD_TRACE_STARTUP_LOGS` environment
  // variable.
  Optional<bool> log_on_startup;

  // `trace_id_128_bit` indicates whether the tracer will generate 128-bit trace
  // IDs.  If true, the tracer will generate 128-bit trace IDs. If false, the
  // tracer will generate 64-bit trace IDs. `trace_id_128_bit` is overridden by
  // the `DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED` environment variable.
  Optional<bool> generate_128bit_trace_ids;

  // `runtime_id` denotes the current run of the application in which the tracer
  // is embedded. If `runtime_id` is not specified, then it defaults to a
  // pseudo-randomly generated value. A server that contains multiple tracers,
  // such as those in the worker threads/processes of a reverse proxy, might
  // specify the same `runtime_id` for all tracer instances in the same run.
  Optional<RuntimeID> runtime_id;

  // Root session ID for stable telemetry correlation across forked workers.
  // Integrations (nginx, httpd, kong) should set this in the master process
  // before workers fork so all Tracers share the same root.
  Optional<std::string> root_session_id;

  // `integration_name` is the name of the product integrating this library.
  // Example: "nginx", "envoy" or "istio".
  Optional<std::string> integration_name;
  // `integration_version` is the version of the product integrating this
  // library.
  // Example: "1.2.3", "6c44da20", "2020.02.13"
  Optional<std::string> integration_version;

  // This field allows for overriding the service name origin to default.
  //
  // Mainly exist for integration configurations purposes.
  // For instance, the default service name for the nginx integration will
  // resolve as 'nginx'. Without this customization, it would be reported as a
  // programmatic value in Datadog's Active Configuration, whereas it is
  // actually the default value for the integration.
  Optional<bool> report_service_as_default;

  /// The maximum number of baggage items that can be stored or propagated.
  Optional<std::size_t> baggage_max_items;

  /// The maximum amount of bytes allowed to be written during tracing context
  /// injection.
  Optional<std::size_t> baggage_max_bytes;

  /// The event scheduler used for scheduling recurring tasks.
  /// By default, it uses `ThreadedEventScheduler`, which runs tasks on a
  /// separate thread.
  std::shared_ptr<EventScheduler> event_scheduler;

  /// `tracing_enabled` indicates whether APM traces and APM trace metrics
  /// are enabled. If `false`, APM-specific traces are and metrics are dropped
  /// This allows other products to operate independently (for example, AppSec).
  /// This is distinct from `report_traces`, which controls whether any traces
  /// are sent at all.
  ///
  /// Overridden by the `DD_APM_TRACING_ENABLED` environment variable. Defaults
  /// to `true`.
  Optional<bool> tracing_enabled;

  // Whether generation of http.endpoint is enabled. This is disabled by
  // default.
  Optional<bool> resource_renaming_enabled;

  // Whether http.endpoint is always calculated, even when http.route is
  // present. This is disabled by default.
  // This option is ignored if `resource_renaming_enabled` is not `true`.
  Optional<bool> resource_renaming_always_simplified_endpoint;

  /// A mapping of process-specific tags used to uniquely identify processes.
  ///
  /// The `process_tags` map allows associating arbitrary string-based keys and
  /// values with a process. These tags are consumed as fact for identifying
  /// processes.
  std::unordered_map<std::string, std::string> process_tags;
};

// `FinalizedTracerConfig` contains `Tracer` implementation details derived from
// a valid `TracerConfig` and accompanying environment.
// `FinalizedTracerConfig` must be obtained by calling `finalize_config`.
class FinalizedTracerConfig final {
  friend Expected<FinalizedTracerConfig> finalize_config(
      const TracerConfig& config, const Clock& clock);
  FinalizedTracerConfig() = default;

 public:
  SpanDefaults defaults;

  std::variant<std::monostate, FinalizedDatadogAgentConfig,
               std::shared_ptr<Collector>>
      collector;

  FinalizedTraceSamplerConfig trace_sampler;
  FinalizedSpanSamplerConfig span_sampler;
  telemetry::FinalizedConfiguration telemetry;

  std::vector<PropagationStyle> injection_styles;
  std::vector<PropagationStyle> extraction_styles;

  bool report_hostname;
  std::size_t tags_header_size;
  std::shared_ptr<Logger> logger;
  bool log_on_startup;
  bool generate_128bit_trace_ids;
  Optional<RuntimeID> runtime_id;
  Optional<std::string> root_session_id;
  Clock clock;
  std::string integration_name;
  std::string integration_version;
  bool report_traces;
  std::unordered_map<ConfigName, std::vector<ConfigMetadata>> metadata;
  Baggage::Options baggage_opts;
  HTTPClient::URL agent_url;
  std::shared_ptr<EventScheduler> event_scheduler;
  std::shared_ptr<HTTPClient> http_client;
  bool tracing_enabled;
  HttpEndpointCalculationMode resource_renaming_mode;
  std::unordered_map<std::string, std::string> process_tags;
};

// Return a `FinalizedTracerConfig` from the specified `config` and from any
// relevant environment variables.  If any configuration is invalid, return an
// `Error`.
// Optionally specify a `clock` used to calculate span start times, span
// durations, and timeouts.  If `clock` is not specified, then `default_clock`
// is used.
Expected<FinalizedTracerConfig> finalize_config(const TracerConfig& config);
Expected<FinalizedTracerConfig> finalize_config(const TracerConfig& config,
                                                const Clock& clock);

}  // namespace tracing
}  // namespace datadog