tracing.hpp

Go to the documentation of this file.

// Copyright 2026 Aniket Kulkarni
// SPDX-License-Identifier: Apache-2.0
 
 
#pragma once
 
#include "neuralplus/export.hpp"
#include "neuralplus/types.hpp"
 
#include <chrono>
#include <cstddef>
#include <functional>
#include <memory>
#include <mutex>
#include <string>
#include <vector>
 
namespace neuralplus {
 
enum class TraceLevel {
    debug,
    info,
    warning,
    error,
};
 
enum class TraceEventType {
    generation_start,
    generation_end,
    provider_start,
    provider_end,
    tool_start,
    tool_end,
    error,
};
 
struct TraceEvent {
    TraceLevel level{TraceLevel::info};
 
    TraceEventType type{TraceEventType::generation_start};
 
    std::chrono::system_clock::time_point timestamp{
        std::chrono::system_clock::now()};
 
    std::string session_id;
 
    std::string run_id;
 
    std::string operation_id;
 
    std::string name;
 
    JsonValue attributes = JsonValue::object();
 
    std::string payload;
};
 
class NEURALPLUS_API Tracer {
public:
    virtual ~Tracer();
 
    virtual void record(const TraceEvent& event) = 0;
 
protected:
    Tracer() = default;
 
private:
    Tracer(const Tracer&) = delete;
    Tracer& operator=(const Tracer&) = delete;
};
 
class NEURALPLUS_API ConsoleTracer final : public Tracer {
public:
    ConsoleTracer();
    ~ConsoleTracer() override;
 
    void record(const TraceEvent& event) override;
 
private:
    ConsoleTracer(const ConsoleTracer&) = delete;
    ConsoleTracer& operator=(const ConsoleTracer&) = delete;
 
    std::mutex mutex_;
};
 
struct FileTracerOptions {
    bool append{true};
 
    bool flush_each_event{false};
 
    bool include_payloads{false};
 
    std::size_t max_bytes{0};
};
 
class NEURALPLUS_API FileTracer final : public Tracer {
public:
    explicit FileTracer(std::string path,
                        FileTracerOptions options = {});
    ~FileTracer() override;
 
    void record(const TraceEvent& event) override;
 
private:
    FileTracer(const FileTracer&) = delete;
    FileTracer& operator=(const FileTracer&) = delete;
 
    class Impl;
    std::unique_ptr<Impl> impl_;
};
 
class NEURALPLUS_API InMemoryTracer final : public Tracer {
public:
    InMemoryTracer();
    ~InMemoryTracer() override;
 
    void record(const TraceEvent& event) override;
 
    [[nodiscard]] std::vector<TraceEvent> events() const;
 
    void clear();
 
private:
    InMemoryTracer(const InMemoryTracer&) = delete;
    InMemoryTracer& operator=(const InMemoryTracer&) = delete;
 
    mutable std::mutex mutex_;
    std::vector<TraceEvent> events_;
};
 
class NEURALPLUS_API FunctionTracer final : public Tracer {
public:
    using Function = std::function<void(const TraceEvent&)>;
 
    explicit FunctionTracer(Function function);
    ~FunctionTracer() override;
 
    void record(const TraceEvent& event) override;
 
private:
    FunctionTracer(const FunctionTracer&) = delete;
    FunctionTracer& operator=(const FunctionTracer&) = delete;
 
    std::mutex mutex_;
    Function function_;
};
 
class NEURALPLUS_API SyslogTracer final : public Tracer {
public:
    explicit SyslogTracer(std::string identity = "neuralplus",
                          int facility = 0);
    ~SyslogTracer() override;
 
    void record(const TraceEvent& event) override;
 
private:
    SyslogTracer(const SyslogTracer&) = delete;
    SyslogTracer& operator=(const SyslogTracer&) = delete;
 
    class Impl;
    std::unique_ptr<Impl> impl_;
};
 
using Tracers = std::vector<std::shared_ptr<Tracer>>;
 
[[nodiscard]] NEURALPLUS_API const char* to_string(TraceLevel level) noexcept;
 
[[nodiscard]] NEURALPLUS_API const char* to_string(TraceEventType type) noexcept;
 
}  // namespace neuralplus