logging.hpp

// Unless explicitly stated otherwise all files in this repository are licensed
// under the Apache License Version 2.0.
//
// This product includes software developed at Datadog (https://www.datadoghq.com/).
// Copyright 2025-Present Datadog, Inc.

#pragma once

#include <cinttypes>
#include <memory>
#include <optional>
#include <string>
#include <string_view>

#include "datadog/attribute.hpp"
#include "datadog/core.hpp"

namespace datadog {

// Forward declarations
namespace impl {
class Logger;
class Logging;
}  // namespace impl

/**
 * Severity at which log messages may be emitted.
 */
enum class LogLevel : uint8_t {
  Debug,
  Info,
  Notice,
  Warn,
  Error,
  Critical,
};

/**
 * Configures the details of a logger upon creation.
 */
struct LoggerConfig {
  friend class Logging;
  friend class impl::Logger;

 private:
  float remote_sample_rate{100.0f};
  std::optional<std::string> service;
  std::optional<std::string> name;
  LogLevel remote_log_threshold{LogLevel::Debug};
  size_t initial_attribute_capacity{0};
  bool enrich_with_rum_context{true};

 public:
  DATADOG_API LoggerConfig();
  DATADOG_API ~LoggerConfig();
  DATADOG_API LoggerConfig(const LoggerConfig&);
  DATADOG_API LoggerConfig& operator=(const LoggerConfig&);
  DATADOG_API LoggerConfig(LoggerConfig&&);
  DATADOG_API LoggerConfig& operator=(LoggerConfig&&);

  /**
   * Sets the remote sample rate to a value between 0.0 and 100.0, indicating what
   * percentage of log events should be sampled.
   */
  DATADOG_API LoggerConfig& SetRemoteSampleRate(float value);
  /**
   * Sets the service name to be used on messages emitted by a logger. If omitted, the
   * logger will use the service name configured globally via CoreConfig.
   */
  DATADOG_API LoggerConfig& SetService(std::string_view value);
  /**
   * Sets the name used to identify a logger in messages emitted by that logger. If
   * omitted, no 'logger.name' property will be present on log events.
   */
  DATADOG_API LoggerConfig& SetName(std::string_view value);
  /**
   * Sets the minimum log level at which messages will be sent to intake. Only messages
   * at or above this level will be considered for sampling; all messages below that
   * level will be dropped. Defaults to LogLevel::Debug, meaning all messages will be
   * sent to intake.
   */
  DATADOG_API LoggerConfig& SetRemoteLogThreshold(LogLevel value);
  /**
   * Sets the initial number of custom attributes for which memory will be preallocated
   * on logger creation. At the default of 0, does not reserve space for custom
   * attributes.
   *
   * Custom attributes may be freely added beyond this limit. Setting an initial
   * capacity is simply a means of optimizing memory allocations based on expected
   * usage.
   */
  DATADOG_API LoggerConfig& SetInitialAttributeCapacity(size_t value);
  /**
   * Controls whether log events generated by this logger will be enriched with current
   * RUM application state, provided that RUM is in use. Defaults to true.
   */
  DATADOG_API LoggerConfig& SetEnrichWithRumContext(bool value);
};

/**
 * Caller-supplied details about an error attached to a log event.
 */
struct LogError {
  std::string_view message;  // Serialized as error.message on both log and RUM events
  std::string_view kind;   // Serialized as error.kind on log events; error.type for RUM
  std::string_view stack;  // Serialized as error.stack on both log and RUM events
};

/**
 * Interface used to emit log messages.
 */
class Logger {
  friend class Logging;

 private:
  struct PrivateCtorTag {};

 public:
  // Callers should use Logging::CreateLogger
  explicit Logger(
      std::unique_ptr<impl::Logger>&& impl,
      DiagnosticHandler diagnostic_handler,
      DiagnosticLevel diagnostic_threshold,
      PrivateCtorTag
  );
  DATADOG_API ~Logger();

  /**
   * Adds or updates a logger-level attribute value that will be included with all
   * messages emitted by this logger. If a logger-level attribute shares its name with a
   * global attribute, the logger-level attribute will take precedence.
   */
  DATADOG_API void AddAttribute(std::string_view name, const Attribute& value);

  /**
   * Removes a logger-level attribute value, if one has been previously added with the
   * given name.
   */
  DATADOG_API void RemoveAttribute(std::string_view name);

  /**
   * Adds a custom tag to this logger.
   *
   * Like custom attributes, a logger's custom tag values are attached to all events
   * emitted by the logger. Whereas attributes can represent complex, JSON-like values,
   * tags are simple `key:value` strings intended to support lightweight filtering,
   * grouping, and aggregation of events.
   *
   * A tag's key is its first ':'-delimited token; and its value is everything that
   * follows the first colon. A tag may be specified without a value, in which case no
   * colon is required.
   *
   * Both keys and values are restricted to a subset of basic ASCII characters: only
   * alphanumeric characters [a-z0-9] and punctuation characters [_:/.-]. A valid tag
   * that includes characters outside of this range will be automatically normalized,
   * e.g. `Foo!:Hello world` will become `foo_:hello_world`.
   *
   * A valid key must begin with a letter. A key will also be considered invalid if it
   * conflicts with the set of keys reserved for internal use, which includes: service,
   * version, env, sdk_version, variant, host, device, and source. Tags with invalid
   * keys will be rejected.
   *
   * A logger may have no more than 100 custom tags, and each tag is limited to 200
   * bytes in length. Any valid tag that exceeds the length limit will be automatically
   * truncated.
   */
  DATADOG_API void AddTag(std::string_view tag);

  /**
   * Adds a custom tag to this logger using separate key and value strings.
   */
  DATADOG_API void AddTag(std::string_view key, std::string_view value);

  /**
   * Removes any previously-added tag that exactly matches the given value (both key and
   * value) after sanitization.
   */
  DATADOG_API void RemoveTag(std::string_view tag);

  /**
   * Removes all previously-added tags whose key matches `key` (after sanitization).
   */
  DATADOG_API void RemoveTagsWithKey(std::string_view key);

  /**
   * Emits a log message at the given level.
   *
   * `err` may be omitted at any log level. When provided, its non-empty fields are
   * included in the resulting log event unconditionally.
   *
   * If `attributes` has type ValueType::Object, each of its named values will be
   * included in the resulting log event, taking precedence over global and logger-level
   * attributes in case of name conflict. If attributes is a value of any other type, it
   * will be ignored.
   */
  DATADOG_API void Log(
      LogLevel level,
      std::string_view message,
      const LogError& err = LogError(),
      const Attribute& attributes = Attribute()
  );

  /**
   * Emits a Debug-level message from the given logger, with optional error details and
   * an optional set of extra attribute values.
   */
  DATADOG_API void Debug(
      std::string_view message,
      const LogError& err = LogError(),
      const Attribute& attributes = Attribute()
  );

  /**
   * Emits an Info-level message from the given logger, with optional error details and
   * an optional set of extra attribute values.
   */
  DATADOG_API void Info(
      std::string_view message,
      const LogError& err = LogError(),
      const Attribute& attributes = Attribute()
  );

  /**
   * Emits a Notice-level message from the given logger, with optional error details and
   * an optional set of extra attribute values.
   */
  DATADOG_API void Notice(
      std::string_view message,
      const LogError& err = LogError(),
      const Attribute& attributes = Attribute()
  );

  /**
   * Emits a Warning-level message from the given logger, with optional error details
   * and an optional set of extra attribute values.
   */
  DATADOG_API void Warn(
      std::string_view message,
      const LogError& err = LogError(),
      const Attribute& attributes = Attribute()
  );

  /**
   * Emits an Error-level message from the given logger, with optional error details and
   * an optional set of extra attribute values.
   *
   * If RUM tracking is active, this call will automatically record a RUM Error in the
   * active view.
   */
  DATADOG_API void Error(
      std::string_view message,
      const LogError& err = LogError(),
      const Attribute& attributes = Attribute()
  );

  /**
   * Emits a Critical-level message from the given logger, with optional error details
   * and an optional set of extra attribute values.
   *
   * If RUM tracking is active, this call will automatically record a RUM Error in the
   * active view.
   */
  DATADOG_API void Critical(
      std::string_view message,
      const LogError& err = LogError(),
      const Attribute& attributes = Attribute()
  );

 private:
  // Forbid copying/moving: we use std::shared_ptr<Logger> at the API boundary
  Logger(const Logger&) = delete;
  Logger& operator=(const Logger&) = delete;
  Logger(Logger&&) = delete;
  Logger& operator=(Logger&&) = delete;

  std::unique_ptr<impl::Logger> _impl;
  DiagnosticHandler _diagnostic_handler;
  DiagnosticLevel _diagnostic_threshold;
};

/**
 * Interface to the Datadog SDK's logging feature.
 */
class Logging {
 private:
  struct PrivateCtorTag {};

 public:
  // Callers should use Logging::Register
  explicit Logging(PrivateCtorTag);
  explicit Logging(
      std::shared_ptr<impl::Logging>&& impl,
      DiagnosticHandler diagnostic_handler,
      DiagnosticLevel diagnostic_threshold,
      PrivateCtorTag
  );
  DATADOG_API ~Logging();

 public:
  /**
   * Registers the logging feature with the core of the Datadog SDK.
   */
  DATADOG_API static std::shared_ptr<Logging> Register(
      const std::shared_ptr<class Core>& core
  );

  /**
   * Adds or updates a global attribute value that will be included with all log
   * messages emitted by all loggers.
   */
  DATADOG_API void AddAttribute(std::string_view name, const Attribute& value);

  /**
   * Removes a global attribute value, if one has been previously added with the given
   * name.
   */
  DATADOG_API void RemoveAttribute(std::string_view name);

  /**
   * Creates and returns a new logger with the given configuration.
   */
  DATADOG_API std::shared_ptr<Logger> CreateLogger(
      const LoggerConfig& config = LoggerConfig()
  );

 private:
  // Forbid copying/moving: we use std::shared_ptr<Logging> at the API boundary
  Logging(const Logging&) = delete;
  Logging& operator=(const Logging&) = delete;
  Logging(Logging&&) = delete;
  Logging& operator=(Logging&&) = delete;

  std::shared_ptr<impl::Logging> _impl;
  DiagnosticHandler _diagnostic_handler;
  DiagnosticLevel _diagnostic_threshold;
};

}  // namespace datadog