Skip to content

Build your personal knowledge base with Trilium Notes

docs(etapi): document the metrics endpoint and correct its default format

Elian Doran09dba77c0a3a
diff --git a/apps/server/internal.openapi.yaml b/apps/server/internal.openapi.yaml
index 6f4f526dee..845b7aed45 100644
--- a/apps/server/internal.openapi.yaml
+++ b/apps/server/internal.openapi.yaml
@@ -2942,7 +2942,7 @@ paths:
schema:
type: string
enum: [prometheus, json]
- default: json
+ default: prometheus
responses:
'200':
description: System metrics
diff --git a/apps/server/spec/etapi/openapi-spec.spec.ts b/apps/server/spec/etapi/openapi-spec.spec.ts
index cef5776cb1..78fdf85907 100644
--- a/apps/server/spec/etapi/openapi-spec.spec.ts
+++ b/apps/server/spec/etapi/openapi-spec.spec.ts
@@ -10,18 +10,15 @@ import etapiAttributeRoutes from "../../src/etapi/attributes.js";
import etapiAuthRoutes from "../../src/etapi/auth.js";
import etapiBackupRoute from "../../src/etapi/backup.js";
import etapiBranchRoutes from "../../src/etapi/branches.js";
+import etapiMetricsRoute from "../../src/etapi/metrics.js";
import etapiNoteRoutes from "../../src/etapi/notes.js";
import etapiRevisionsRoutes from "../../src/etapi/revisions.js";
import etapiSpecialNoteRoutes from "../../src/etapi/special_notes.js";
let app: Application;
-/**
- * Endpoints served under /etapi that the specification deliberately leaves out: it cannot
- * usefully describe itself, and /etapi/metrics is an operational endpoint rather than part
- * of the note API. Everything else must be documented.
- */
-const UNDOCUMENTED_ROUTES = new Set(["/etapi.openapi.yaml", "/metrics"]);
+/** The specification cannot usefully describe the route serving it. Everything else must be documented. */
+const UNDOCUMENTED_ROUTES = new Set(["/etapi.openapi.yaml"]);
describe("etapi/etapi.openapi.yaml", () => {
beforeAll(async () => {
@@ -69,6 +66,7 @@ function collectEtapiRoutes() {
etapiAttributeRoutes.register(router);
etapiBackupRoute.register(router);
etapiBranchRoutes.register(router);
+ etapiMetricsRoute.register(router);
etapiNoteRoutes.register(router);
etapiRevisionsRoutes.register(router);
etapiSpecialNoteRoutes.register(router);
diff --git a/apps/server/src/assets/etapi.openapi.yaml b/apps/server/src/assets/etapi.openapi.yaml
index 486a901e7a..7bb5bc2056 100644
--- a/apps/server/src/assets/etapi.openapi.yaml
+++ b/apps/server/src/assets/etapi.openapi.yaml
@@ -1035,6 +1035,49 @@ paths:
application/json; charset=utf-8:
schema:
$ref: "#/components/schemas/Error"
+ /metrics:
+ get:
+ summary: Get instance metrics
+ description: |
+ Returns instance and database metrics for monitoring: note, attachment, revision,
+ branch, attribute and blob counts, note and attachment type breakdowns, version
+ information and database size. Counts only — no note titles, content or attributes.
+
+ The same data is served by GET /api/metrics to the web session.
+ operationId: getMetrics
+ parameters:
+ - name: format
+ in: query
+ required: false
+ description: Response format. Defaults to Prometheus text.
+ schema:
+ type: string
+ enum: [prometheus, json]
+ default: prometheus
+ responses:
+ "200":
+ description: instance metrics
+ content:
+ text/plain:
+ schema:
+ type: string
+ example: |
+ # HELP trilium_info Trilium instance information
+ # TYPE trilium_info gauge
+ trilium_info{version="0.99.3",db_version="231"} 1 1701432000
+
+ # HELP trilium_notes_total Total number of notes including deleted
+ # TYPE trilium_notes_total gauge
+ trilium_notes_total 1234 1701432000
+ application/json:
+ schema:
+ $ref: "#/components/schemas/Metrics"
+ default:
+ description: unexpected error
+ content:
+ application/json; charset=utf-8:
+ schema:
+ $ref: "#/components/schemas/Error"
components:
securitySchemes:
EtapiTokenAuth:
@@ -1466,3 +1509,91 @@ components:
canBeUndeleted:
type: boolean
description: Whether the note can be undeleted (only present for deleted notes)
+ Metrics:
+ type: object
+ description: Instance and database metrics, as served by GET /etapi/metrics?format=json
+ properties:
+ version:
+ type: object
+ properties:
+ app:
+ type: string
+ example: "0.99.3"
+ db:
+ type: integer
+ example: 231
+ node:
+ type: string
+ example: v22.14.0
+ sync:
+ type: integer
+ example: 35
+ buildDate:
+ type: string
+ example: "2024-09-07T18:36:34Z"
+ buildRevision:
+ type: string
+ example: 7c0d6930fa8f20d269dcfbcbc8f636a25f6bb9a7
+ database:
+ type: object
+ properties:
+ totalNotes:
+ type: integer
+ deletedNotes:
+ type: integer
+ activeNotes:
+ type: integer
+ protectedNotes:
+ type: integer
+ totalAttachments:
+ type: integer
+ deletedAttachments:
+ type: integer
+ activeAttachments:
+ type: integer
+ totalRevisions:
+ type: integer
+ totalBranches:
+ type: integer
+ totalAttributes:
+ type: integer
+ totalBlobs:
+ type: integer
+ totalEtapiTokens:
+ type: integer
+ totalRecentNotes:
+ type: integer
+ noteTypes:
+ type: object
+ description: Number of active notes per note type
+ additionalProperties:
+ type: integer
+ example:
+ text: 800
+ code: 200
+ attachmentTypes:
+ type: object
+ description: Number of active attachments per MIME type
+ additionalProperties:
+ type: integer
+ example:
+ image/png: 45
+ application/pdf: 14
+ statistics:
+ type: object
+ properties:
+ oldestNote:
+ type: string
+ nullable: true
+ newestNote:
+ type: string
+ nullable: true
+ lastModified:
+ type: string
+ nullable: true
+ databaseSizeBytes:
+ type: integer
+ nullable: true
+ timestamp:
+ type: string
+ example: "2024-12-01T12:00:00.000Z"