Package io.roastedroot.proxywasm

Interface MetricsHandler

  • All Known Implementing Classes:
    SimpleMetricsHandler
    public interface MetricsHandler
    Defines the contract for handling metrics operations initiated by a Proxy-WASM module. Implementations of this interface are responsible for interacting with the underlying metrics system of the host environment (Prometheus etc.).

    The host environment provides implementations of these methods to allow WASM modules to define, manipulate, and retrieve metric values.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static MetricsHandler DEFAULT
      A default, non-functional instance of MetricsHandler.

    • Method Summary

      All Methods Instance Methods Default Methods 
      Modifier and Type Method Description
      default int defineMetric​(MetricType metricType, String name)
      Defines a new metric.
      default long getMetric​(int metricId)
      Retrieves the current value of a metric.
      default io.roastedroot.proxywasm.internal.WasmResult incrementMetric​(int metricId, long value)
      Increments a metric's value (typically used for Counters).
      default io.roastedroot.proxywasm.internal.WasmResult recordMetric​(int metricId, long value)
      Records a value for a metric (typically used for Gauges or Histograms).
      default io.roastedroot.proxywasm.internal.WasmResult removeMetric​(int metricId)
      Removes or deletes a previously defined metric.

    • Field Detail

      • DEFAULT

        static final MetricsHandler DEFAULT
        A default, non-functional instance of MetricsHandler. This instance throws WasmException with WasmResult.UNIMPLEMENTED for methods that define or retrieve metrics, and returns WasmResult.UNIMPLEMENTED for methods that modify or remove metrics. Useful as a placeholder or base when only a subset of metrics functionality is needed.

    • Method Detail

      • defineMetric

        default int defineMetric​(MetricType metricType,
                         String name)
                  throws WasmException
        Defines a new metric.
        Parameters:
        metricType - The type of the metric (e.g., Counter, Gauge, Histogram).
        name - The name of the metric.
        Returns:
        A unique identifier (metric ID) for the newly defined metric.
        Throws:
        WasmException - If the metric cannot be defined (e.g., name conflict, unsupported type, or if the operation is unimplemented by the host).

      • removeMetric

        default io.roastedroot.proxywasm.internal.WasmResult removeMetric​(int metricId)
        Removes or deletes a previously defined metric.
        Parameters:
        metricId - The unique identifier of the metric to remove.
        Returns:
        A WasmResult indicating the outcome of the operation (e.g., OK, NOT_FOUND, UNIMPLEMENTED).

      • recordMetric

        default io.roastedroot.proxywasm.internal.WasmResult recordMetric​(int metricId,
                                                                  long value)
        Records a value for a metric (typically used for Gauges or Histograms).
        Parameters:
        metricId - The unique identifier of the metric.
        value - The value to record.
        Returns:
        A WasmResult indicating the outcome of the operation (e.g., OK, BAD_ARGUMENT, UNIMPLEMENTED).

      • incrementMetric

        default io.roastedroot.proxywasm.internal.WasmResult incrementMetric​(int metricId,
                                                                     long value)
        Increments a metric's value (typically used for Counters).
        Parameters:
        metricId - The unique identifier of the metric.
        value - The amount to increment by (can be negative to decrement, although convention is usually positive).
        Returns:
        A WasmResult indicating the outcome of the operation (e.g., OK, BAD_ARGUMENT, UNIMPLEMENTED).

      • getMetric

        default long getMetric​(int metricId)
                throws WasmException
        Retrieves the current value of a metric.
        Parameters:
        metricId - The unique identifier of the metric.
        Returns:
        The current value of the metric.
        Throws:
        WasmException - If the metric cannot be retrieved (e.g., metric not found, type mismatch, or if the operation is unimplemented by the host).