include/paimon/metrics.h

/*
 * Copyright 2024-present Alibaba Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#pragma once

#include <cstdint>
#include <map>
#include <memory>
#include <string>

#include "paimon/type_fwd.h"

namespace paimon {

/// Abstract interface for collecting and managing performance metrics in Paimon operations.
///
/// This class provides a unified interface for tracking various performance metrics
/// such as counters for read/write operations, I/O statistics, and other operational
/// measurements. It serves as the base class for concrete implementations like `MetricsImpl`.
// TODO(yonghao.fyh): add histogram in the future
class PAIMON_EXPORT Metrics {
 public:
    virtual ~Metrics() = default;

    /// Set the value of a specific counter metric.
    /// @param metric_name The name/key of the metric to set.
    /// @param metric_value The value to set for this metric.
    virtual void SetCounter(const std::string& metric_name, uint64_t metric_value) = 0;

    /// Get the current value of a specific counter metric.
    /// @param metric_name The name/key of the metric to retrieve.
    /// @return The current value of the metric, or `Status::KeyError` if the metric doesn't exist.
    virtual Result<uint64_t> GetCounter(const std::string& metric_name) const = 0;

    /// Get all counter metrics as a map.
    /// @return A map containing all metric names and their current values.
    virtual std::map<std::string, uint64_t> GetAllCounters() const = 0;

    /// Merge metrics from another Metrics instance into this one.
    ///
    /// For metrics that exist in both instances, the values are added together.
    /// For metrics that only exist in the other instance, they are copied over.
    /// This operation is useful for aggregating metrics from multiple sources.
    ///
    /// @param other The other Metrics instance to merge from. If `other` is nullptr or same as
    /// this, no operation is performed.
    virtual void Merge(const std::shared_ptr<Metrics>& other) = 0;

    /// Convert all metrics to a JSON string representation.
    /// @return A JSON string containing all metric names and values, e.g.,
    /// `{"metric1":100,"metric2":200}`.
    virtual std::string ToString() const = 0;
};

}  // namespace paimon