runtime/statsobj.h - main - githubmirror/rsyslog

runtime/statsobj.h
313 строк13 KB
Rainer Gerhards
stats: harden Prometheus renderer failures
19 июл 2026, 16:00
19 июл 2026, 16:000c69c58
/* The statsobj object.
 *
 * Copyright 2010-2026 Rainer Gerhards and Adiscon GmbH.
 *
 * This file is part of the rsyslog runtime library.
 *
 * 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
 *       -or-
 *       see COPYING.ASL20 in the source distribution
 *
 * 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.
 */
/**
 * @file statsobj.h
 * @brief Interface of the rsyslog statistics object
 *
 * A statistics object (statsobj_t) represents a set of counters that
 * describe activity within a subsystem. Each object keeps a doubly
 * linked list of counters and all objects are maintained in a global
 * list protected by a mutex. The counters are either 64 bit integers
 * (ctrType_IntCtr) or plain int values (ctrType_Int) and can be marked
 * resettable. Statistics are only gathered while the global
 * ::GatherStats flag is non-zero.
 *
 * Counters can be reported in multiple formats via the GetAllStatsLines()
 * interface:
 *  - ::statsFmt_Legacy     classic key=value pairs
 *  - ::statsFmt_JSON       valid JSON structures
 *  - ::statsFmt_JSON_ES    JSON with dot replacement for Elasticsearch
 *  - ::statsFmt_CEE        Project Lumberjack / CEE format
 *  - ::statsFmt_Prometheus Prometheus text exposition format
 *
 * The caller supplies a callback that receives each generated line.
 * After emission counters flagged with CTR_FLAG_RESETTABLE may be
 * cleared if requested.
 */
#ifndef INCLUDED_STATSOBJ_H
#define INCLUDED_STATSOBJ_H

#include "atomic.h"

/* The following data item is somewhat dirty, in that it does not follow
 * our usual object calling conventions. However, much like with "Debug", we
 * do this to gain speed. If we finally come to a platform that does not
 * provide resolution of names for dynamically loaded modules, we need to find
 * a work-around, but until then, we use the direct access.
 * If set to 0, statistics are not gathered, otherwise they are.
 */
extern int GatherStats;

/* our basic counter type -- need 32 bit on 32 bit platform.
 * IMPORTANT: this type *MUST* be supported by atomic instructions!
 */
typedef uint64 intctr_t;

/* counter types */
typedef enum statsCtrType_e { ctrType_IntCtr, ctrType_Int } statsCtrType_t;

/* stats line format types */
typedef enum statsFmtType_e {
    statsFmt_Legacy,
    statsFmt_JSON,
    statsFmt_JSON_ES,
    statsFmt_CEE,
    /**
     * Prometheus text‐exposition format:
     * For each counter, emit:
     *   # HELP <obj>_<ctr> (optional generic text)
     *   # TYPE <obj>_<ctr> counter
     *   <obj>_<ctr> <value>
     */
    statsFmt_Prometheus
} statsFmtType_t;

/* counter flags */
#define CTR_FLAG_NONE 0
#define CTR_FLAG_RESETTABLE 1
#define CTR_FLAG_MUST_RESET 2

/* statsobj flags */
#define STATSOBJ_FLAG_NONE 0
#define STATSOBJ_FLAG_DO_PREPEND 1

/**
 * Callback type for native counter iteration via GetAllCounters().
 *
 * @param ctx       User context pointer passed to GetAllCounters()
 * @param obj_name  Name of the statsobj instance (may be NULL/empty)
 * @param obj_origin Origin of the statsobj (e.g., "resource-usage", "core.queue")
 * @param ctr_name  Name of the counter
 * @param ctr_type  Type of counter (ctrType_IntCtr or ctrType_Int)
 * @param value     Current counter value (read atomically for IntCtr, best-effort for Int)
 * @param flags     Counter flags (CTR_FLAG_RESETTABLE, etc.)
 * @return RS_RET_OK to continue iteration, error code to abort
 *
 * THREAD SAFETY:
 * - ctrType_IntCtr: value is read atomically (uint64 on aligned address)
 * - ctrType_Int: value is read without application lock; may be stale but acceptable
 *   for monitoring. These counters are typically gauges (queue size, open files)
 *   protected by application-level mutexes that the stats system cannot acquire.
 *
 * LOCKING CONSTRAINT:
 * - The counter list mutex is HELD during callback invocation to prevent concurrent
 *   list modification. Callbacks MUST complete quickly and MUST NOT call back into
 *   statsobj or deadlock will occur.
 */
typedef rsRetVal (*statsobj_counter_cb_t)(void *ctx,
                                          const uchar *obj_name,
                                          const uchar *obj_origin,
                                          const uchar *ctr_name,
                                          statsCtrType_t ctr_type,
                                          uint64_t value,
                                          int8_t flags);

/* helper entity, the counter */
typedef struct ctr_s {
    uchar *name;
    statsCtrType_t ctrType;
    union {
        intctr_t *pIntCtr;
        int *pInt;
    } val;
    int8_t flags;
    struct ctr_s *next, *prev;
} ctr_t;

/* the statsobj object */
struct statsobj_s {
    BEGINobjInstance
        ; /* Data to implement generic object - MUST be the first data element! */
        uchar *name;
        uchar *origin;
        uchar *reporting_ns;
        statsobj_read_notifier_t read_notifier;
        void *read_notifier_ctx;
        pthread_mutex_t mutCtr; /* to guard counter linked-list ops */
        ctr_t *ctrRoot; /* doubly-linked list of statsobj counters */
        ctr_t *ctrLast;
        int flags;
        /* used to link ourselves together */
        statsobj_t *prev;
        statsobj_t *next;
};

struct sender_stats {
    const uchar *sender;
    uint64_t nMsgs;
    time_t lastSeen;
};


/* interfaces */
BEGINinterface(statsobj) /* name must also be changed in ENDinterface macro! */
    INTERFACEObjDebugPrint(statsobj);
    rsRetVal (*Construct)(statsobj_t **ppThis);
    rsRetVal (*ConstructFinalize)(statsobj_t *pThis);
    rsRetVal (*Destruct)(statsobj_t **ppThis);
    rsRetVal (*SetName)(statsobj_t *pThis, uchar *name);
    rsRetVal (*SetOrigin)(statsobj_t *pThis, uchar *name); /* added v12, 2014-09-08 */
    rsRetVal (*SetReadNotifier)(statsobj_t *pThis, statsobj_read_notifier_t notifier, void *ctx);
    rsRetVal (*SetReportingNamespace)(statsobj_t *pThis, uchar *ns);
    void (*SetStatsObjFlags)(statsobj_t *pThis, int flags);
    rsRetVal (*GetAllStatsLines)(rsRetVal (*cb)(void *, const char *), void *usrptr, statsFmtType_t fmt,
                                 int8_t bResetCtr);
    rsRetVal (*GetAllCounters)(statsobj_counter_cb_t cb, void *ctx);
    /**
     * Encode a complete metric name for Prometheus text and Remote Write.
     *
     * @param raw_name non-NULL NUL-terminated metric name to encode
     * @param encoded_name non-NULL output location for the heap allocation
     * @return RS_RET_OK on success, RS_RET_PARAM_ERROR for NULL arguments,
     *         or RS_RET_OUT_OF_MEMORY on allocation failure
     */
    rsRetVal (*EncodePrometheusMetricName)(const uchar *raw_name, char **encoded_name);
    /**
     * @brief Register a counter value with a stats object.
     *
     * The counter name is duplicated internally; the caller retains ownership
     * of @p ctrName and may free/modify it after this call returns.
     *
     * @param pThis    target stats object
     * @param ctrName  counter name (copied internally)
     * @param ctrType  counter type
     * @param flags    counter flags
     * @param pCtr     pointer to caller-owned counter storage
     *
     * @note The storage referenced by @p pCtr must remain valid for at least
     * the lifetime of the registered counter entry in @p pThis.
     */
    rsRetVal (*AddCounter)(statsobj_t *pThis, const uchar *ctrName, statsCtrType_t ctrType, int8_t flags, void *pCtr);
    /**
     * @brief Register a managed counter entry and optionally link it into
     * the stats object's counter list.
     *
     * The counter name is duplicated internally; the caller retains ownership
     * of @p ctrName and may free/modify it after this call returns.
     *
     * On success, @p ref receives the created entry handle, which can be used
     * with `DestructCounter()` (if linked) or `DestructUnlinkedCounter()`
     * (if not linked) according to the chosen lifecycle.
     *
     * @param pThis    target stats object
     * @param ctrName  counter name (copied internally)
     * @param ctrType  counter type
     * @param flags    counter flags
     * @param pCtr     pointer to caller-owned counter storage
     * @param ref      out: created counter entry handle
     * @param linked   if non-zero, entry is linked into @p pThis and follows
     *                 object lifecycle unless explicitly destructed
     *
     * @note The storage referenced by @p pCtr must remain valid for at least
     * the lifetime of the created counter entry.
     */
    rsRetVal (*AddManagedCounter)(statsobj_t *pThis, const uchar *ctrName, statsCtrType_t ctrType, int8_t flags,
                                  void *pCtr, ctr_t **ref, int8_t linked);
    rsRetVal (*AddPreCreatedCtr)(statsobj_t *pThis, ctr_t *ctr);
    void (*DestructCounter)(statsobj_t *pThis, ctr_t *ref);
    void (*DestructUnlinkedCounter)(ctr_t *ctr);
    ctr_t *(*UnlinkAllCounters)(statsobj_t *pThis);
    rsRetVal (*EnableStats)(void);
ENDinterface(statsobj)
#define statsobjCURR_IF_VERSION 16 /* increment whenever you change the interface structure! */
/* Changes
 * v2-v9 rserved for future use in "older" version branches
 * v10, 2012-04-01: GetAllStatsLines got fmt parameter
 * v11, 2013-09-07: - add "flags" to AddCounter API
 *                  - GetAllStatsLines got parameter telling if ctrs shall be reset
 * v13, 2016-05-19: GetAllStatsLines cb data type changed (char* instead of cstr)
 * v14, 2026-02-01: Add GetAllCounters() native counter iteration API
 * v15, 2026-06-23: AddPreCreatedCtr returns rsRetVal for lock failure propagation
 * v16, 2026-07-15: add EncodePrometheusMetricName() for shared exporter name escaping
 */


/* prototypes */
PROTOTYPEObjFull(statsobj);
PROTOTYPEObjDebugPrint(statsobj);

rsRetVal statsRecordSender(const uchar *sender, unsigned nMsgs, time_t lastSeen);
/* checkGoneAwaySenders() is part of this module because all it needs is
 * done by this module, so even though it's own processing is not directly
 * related to stats, it makes sense to do it here... -- rgerhards, 2016-02-01
 */
void checkGoneAwaySenders(time_t);

/* macros to handle stats counters
 * These are to be used by "counter providers". Note that we MUST
 * specify the mutex name, even though at first it looks like it
 * could be automatically be generated via e.g. "mut##ctr".
 * Unfortunately, this does not work if counter is e.g. "pThis->ctr".
 * So we decided, for clarity, to always insist on specifying the mutex
 * name (after all, it's just a few more keystrokes...).
 * --------------------------------------------------------------------
 *                               NOTE WELL
 * --------------------------------------------------------------------
 * There are actually two types of stats counters: "regular" counters,
 * which are only used for stats purposes and "dual" counters, which
 * are primarily used for other purposes but can be included in stats
 * as well. ALL regular counters MUST be initialized with
 * STATSCOUNTER_INIT and only be modified by STATSCOUNTER_* functions.
 * They MUST NOT be used for any other purpose (if this seems to make
 * sense, consider changing it to a dual counter).
 * Dual counters are somewhat dangerous in that a single variable is
 * used for two purposes: the actual application need and stats
 * counting. However, this is supported for performance reasons, as it
 * provides insight into the inner engine workings without need for
 * additional counters (and their maintenance code). Dual counters
 * MUST NOT be modified by STATSCOUNTER_* functions. Most importantly,
 * it is expected that the actua application code provides proper
 * (enough) synchronized access to these counters. Most importantly,
 * this means they have NO stats-system mutex associated to them.
 *
 * The interface function AddCounter() is a read-only function. It
 * only provides the stats subsystem with a reference to a counter.
 * It is irrelevant if the counter is a regular or dual one. For that
 * reason, AddCounter() must not modify the counter contents, as in
 * the case of a dual counter application code may be broken.
 */
#define STATSCOUNTER_DEF(ctr, mut) \
    intctr_t ctr;                  \
    DEF_ATOMIC_HELPER_MUT64(mut);

#define STATSCOUNTER_INIT(ctr, mut) \
    INIT_ATOMIC_HELPER_MUT64(mut);  \
    ctr = 0;

#define STATSCOUNTER_ENABLED() (PREFER_FETCH_32BIT(GatherStats) != 0)

#define STATSCOUNTER_INC(ctr, mut) \
    if (STATSCOUNTER_ENABLED()) ATOMIC_INC_uint64_RELAXED(&ctr, &mut);

#define STATSCOUNTER_ADD(ctr, mut, delta) \
    if (STATSCOUNTER_ENABLED()) ATOMIC_ADD_uint64_RELAXED(&ctr, &mut, delta);

#define STATSCOUNTER_DEC(ctr, mut) \
    if (STATSCOUNTER_ENABLED()) ATOMIC_DEC_uint64_RELAXED(&ctr, &mut);

/* the next macro works only if the variable is already guarded
 * by mutex (or the users risks a wrong result). It is assumed
 * that there are not concurrent operations that modify the counter.
 */
#define STATSCOUNTER_SETMAX_NOMUT(ctr, newmax) \
    if (STATSCOUNTER_ENABLED() && ((newmax) > (ctr))) ctr = newmax;

#endif /* #ifndef INCLUDED_STATSOBJ_H */