taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

api-observability.rst (2364B)

      1 ..
      2   This file is part of GNU TALER.
      3 
      4   Copyright (C) 2025 Taler Systems SA
      5 
      6   TALER is free software; you can redistribute it and/or modify it under the
      7   terms of the GNU Affero General Public License as published by the Free Software
      8   Foundation; either version 2.1, or (at your option) any later version.
      9 
     10   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     11   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     12   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     13 
     14   You should have received a copy of the GNU Affero General Public License along with
     15   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     16 
     17 .. target audience: developer, core developer
     18 
     19 .. _observability-api:
     20 
     21 ===============================
     22 Taler Observability RESTful API
     23 ===============================
     24 
     25 Introduction
     26 ------------
     27 
     28 This section describes the API offered by many Taler components. The API is
     29 used to track the internal state of a Taler component.
     30 
     31 ---------------
     32 Version History
     33 ---------------
     34 
     35 The current protocol version is **v0**.
     36 
     37 * This API is to be used by Prometheus and other external tools.
     38 
     39 **Version history:**
     40 
     41 * ``v0``: Initial version.
     42 
     43 **Upcoming versions:**
     44 
     45 * None anticipated.
     46 
     47 **Ideas for future version:**
     48 
     49 * ``vXXX``: marker for features not yet targeted for release
     50 
     51 
     52 Config
     53 ------
     54 
     55 .. http:get:: /config
     56 
     57   Return the protocol version and configuration information about the bank.
     58 
     59   **Response:**
     60 
     61   :http:statuscode:`200 OK`:
     62     Response is a `Config`.
     63 
     64   **Details:**
     65 
     66   .. ts:def:: Config
     67 
     68     interface Config {
     69       // Name of the API.
     70       name: "taler-observability";
     71 
     72       // libtool-style representation of the Bank protocol version, see
     73       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
     74       // The format is "current:revision:age".
     75       version: string;
     76     }
     77 
     78 Metrics
     79 -------
     80 
     81 .. http:get:: /metrics
     82 
     83   Exposes application metrics in the Prometheus exposition format. These metrics can be scraped by Prometheus or other monitoring systems for observability, alerting, and analysis.
     84 
     85   **Response:**
     86 
     87   :http:statuscode:`200 Ok`:
     88     Response woth metrics in the Prometheus text format.
     89   :http:statuscode:`401 Unauthorized`:
     90     Authentication failed, likely the credentials are wrong.