diff --git a/changelog.d/856.doc b/changelog.d/856.doc new file mode 100644 index 000000000..b73fc1907 --- /dev/null +++ b/changelog.d/856.doc @@ -0,0 +1 @@ +Generally tidy up and improve metrics documentation. \ No newline at end of file diff --git a/docs/metrics.md b/docs/metrics.md index db01bc40e..94cdfa679 100644 --- a/docs/metrics.md +++ b/docs/metrics.md @@ -10,12 +10,14 @@ metrics: port: 9002 ``` +Hookshot will then provide metrics on `127.0.0.1` at port `9002`. + An example dashboard that can be used with [Grafana](https://grafana.com) can be found at [/contrib/hookshot-dashboard.json](https://github.com/matrix-org/matrix-hookshot/blob/main/contrib/hookshot-dashboard.json). There are 3 variables at the top of the dashboard: ![image](https://user-images.githubusercontent.com/2803622/179366574-1bb83e30-05c6-4558-9e66-e813e85b3a6e.png) -Select the Prometheus with your Hookshot metrics as Data Source. Set Interval to your scraping interval. Set 2x Interval to twice the Interval value ([why?](https://github.com/matrix-org/matrix-hookshot/pull/407#issuecomment-1186251618)). +Select the Prometheus instance with your Hookshot metrics as Data Source. Set Interval to your scraping interval. Set 2x Interval to twice the Interval value ([why?](https://github.com/matrix-org/matrix-hookshot/pull/407#issuecomment-1186251618)). Below is the generated list of Prometheus metrics for Hookshot. @@ -24,29 +26,29 @@ Below is the generated list of Prometheus metrics for Hookshot. | Metric | Help | Labels | |--------|------|--------| | hookshot_webhooks_http_request | Number of requests made to the hookshot webhooks handler | path, method | -| hookshot_provisioning_http_request | Number of requests made to the hookshot webhooks handler | path, method | +| hookshot_provisioning_http_request | Number of requests made to the hookshot provisioner handler | path, method | | hookshot_queue_event_pushes | Number of events pushed through the queue | event | -| hookshot_connection_event_failed | The number of events that failed to process | event, connectionId | -| hookshot_connections | The number of active hookshot connections | service | +| hookshot_connection_event_failed | Number of events that failed to process | event, connectionId | +| hookshot_connections | Number of active hookshot connections | service | | hookshot_notifications_push | Number of notifications pushed | service | -| hookshot_notifications_service_up | Is the notification service up or down | service | +| hookshot_notifications_service_up | Whether the notification service is up or down | service | | hookshot_notifications_watchers | Number of notifications watchers running | service | -| hookshot_feeds_count | The number of RSS feeds that hookshot is subscribed to | | -| hookshot_feeds_fetch_ms | The time taken for hookshot to fetch all feeds | | -| hookshot_feeds_failing | The number of RSS feeds that hookshot is failing to read | reason | +| hookshot_feeds_count | Number of RSS feeds that hookshot is subscribed to | | +| hookshot_feeds_fetch_ms | Time taken for hookshot to fetch all feeds | | +| hookshot_feeds_failing | Number of RSS feeds that hookshot is failing to read | reason | ## matrix | Metric | Help | Labels | |--------|------|--------| -| matrix_api_calls | The number of Matrix client API calls made | method | -| matrix_api_calls_failed | The number of Matrix client API calls which failed | method | -| matrix_appservice_events | The number of events sent over the AS API | | -| matrix_appservice_decryption_failed | The number of events sent over the AS API that failed to decrypt | | +| matrix_api_calls | Number of Matrix client API calls made | method | +| matrix_api_calls_failed | Number of Matrix client API calls which failed | method | +| matrix_appservice_events | Number of events sent over the AS API | | +| matrix_appservice_decryption_failed | Number of events sent over the AS API that failed to decrypt | | ## feed | Metric | Help | Labels | |--------|------|--------| -| feed_count | (Deprecated) The number of RSS feeds that hookshot is subscribed to | | -| feed_fetch_ms | (Deprecated) The time taken for hookshot to fetch all feeds | | -| feed_failing | (Deprecated) The number of RSS feeds that hookshot is failing to read | reason | +| feed_count | (Deprecated) Number of RSS feeds that hookshot is subscribed to | | +| feed_fetch_ms | (Deprecated) Time taken for hookshot to fetch all feeds | | +| feed_failing | (Deprecated) Number of RSS feeds that hookshot is failing to read | reason | ## process | Metric | Help | Labels | |--------|------|--------| diff --git a/scripts/build-metrics-docs.ts b/scripts/build-metrics-docs.ts index ef78293c3..f942b3b09 100644 --- a/scripts/build-metrics-docs.ts +++ b/scripts/build-metrics-docs.ts @@ -35,12 +35,14 @@ metrics: port: 9002 \`\`\` +Hookshot will then provide metrics on \`127.0.0.1\` at port \`9002\`. + An example dashboard that can be used with [Grafana](https://grafana.com) can be found at [/contrib/hookshot-dashboard.json](https://github.com/matrix-org/matrix-hookshot/blob/main/contrib/hookshot-dashboard.json). There are 3 variables at the top of the dashboard: ![image](https://user-images.githubusercontent.com/2803622/179366574-1bb83e30-05c6-4558-9e66-e813e85b3a6e.png) -Select the Prometheus with your Hookshot metrics as Data Source. Set Interval to your scraping interval. Set 2x Interval to twice the Interval value ([why?](https://github.com/matrix-org/matrix-hookshot/pull/407#issuecomment-1186251618)). +Select the Prometheus instance with your Hookshot metrics as Data Source. Set Interval to your scraping interval. Set 2x Interval to twice the Interval value ([why?](https://github.com/matrix-org/matrix-hookshot/pull/407#issuecomment-1186251618)). Below is the generated list of Prometheus metrics for Hookshot. diff --git a/src/Metrics.ts b/src/Metrics.ts index cd5d0c528..c639e6b32 100644 --- a/src/Metrics.ts +++ b/src/Metrics.ts @@ -36,28 +36,28 @@ export class Metrics { this.expressRouter.get('/metrics', this.metricsFunc.bind(this)); this.webhooksHttpRequest = new Counter({ name: "hookshot_webhooks_http_request", help: "Number of requests made to the hookshot webhooks handler", labelNames: ["path", "method"], registers: [this.registry]}); - this.provisioningHttpRequest = new Counter({ name: "hookshot_provisioning_http_request", help: "Number of requests made to the hookshot webhooks handler", labelNames: ["path", "method"], registers: [this.registry]}); + this.provisioningHttpRequest = new Counter({ name: "hookshot_provisioning_http_request", help: "Number of requests made to the hookshot provisioner handler", labelNames: ["path", "method"], registers: [this.registry]}); this.messageQueuePushes = new Counter({ name: "hookshot_queue_event_pushes", help: "Number of events pushed through the queue", labelNames: ["event"], registers: [this.registry]}); - this.connectionsEventFailed = new Counter({ name: "hookshot_connection_event_failed", help: "The number of events that failed to process", labelNames: ["event", "connectionId"], registers: [this.registry]}); - this.connections = new Gauge({ name: "hookshot_connections", help: "The number of active hookshot connections", labelNames: ["service"], registers: [this.registry]}); + this.connectionsEventFailed = new Counter({ name: "hookshot_connection_event_failed", help: "Number of events that failed to process", labelNames: ["event", "connectionId"], registers: [this.registry]}); + this.connections = new Gauge({ name: "hookshot_connections", help: "Number of active hookshot connections", labelNames: ["service"], registers: [this.registry]}); this.notificationsPush = new Counter({ name: "hookshot_notifications_push", help: "Number of notifications pushed", labelNames: ["service"], registers: [this.registry]}); - this.notificationsServiceUp = new Gauge({ name: "hookshot_notifications_service_up", help: "Is the notification service up or down", labelNames: ["service"], registers: [this.registry]}); + this.notificationsServiceUp = new Gauge({ name: "hookshot_notifications_service_up", help: "Whether the notification service is up or down", labelNames: ["service"], registers: [this.registry]}); this.notificationsWatchers = new Gauge({ name: "hookshot_notifications_watchers", help: "Number of notifications watchers running", labelNames: ["service"], registers: [this.registry]}); - this.matrixApiCalls = new Counter({ name: "matrix_api_calls", help: "The number of Matrix client API calls made", labelNames: ["method"], registers: [this.registry]}); - this.matrixApiCallsFailed = new Counter({ name: "matrix_api_calls_failed", help: "The number of Matrix client API calls which failed", labelNames: ["method"], registers: [this.registry]}); + this.matrixApiCalls = new Counter({ name: "matrix_api_calls", help: "Number of Matrix client API calls made", labelNames: ["method"], registers: [this.registry]}); + this.matrixApiCallsFailed = new Counter({ name: "matrix_api_calls_failed", help: "Number of Matrix client API calls which failed", labelNames: ["method"], registers: [this.registry]}); - this.matrixAppserviceEvents = new Counter({ name: "matrix_appservice_events", help: "The number of events sent over the AS API", labelNames: [], registers: [this.registry]}); - this.matrixAppserviceDecryptionFailed = new Counter({ name: "matrix_appservice_decryption_failed", help: "The number of events sent over the AS API that failed to decrypt", registers: [this.registry]}); + this.matrixAppserviceEvents = new Counter({ name: "matrix_appservice_events", help: "Number of events sent over the AS API", labelNames: [], registers: [this.registry]}); + this.matrixAppserviceDecryptionFailed = new Counter({ name: "matrix_appservice_decryption_failed", help: "Number of events sent over the AS API that failed to decrypt", registers: [this.registry]}); - this.feedsCount = new Gauge({ name: "hookshot_feeds_count", help: "The number of RSS feeds that hookshot is subscribed to", labelNames: [], registers: [this.registry]}); - this.feedFetchMs = new Gauge({ name: "hookshot_feeds_fetch_ms", help: "The time taken for hookshot to fetch all feeds", labelNames: [], registers: [this.registry]}); - this.feedsFailing = new Gauge({ name: "hookshot_feeds_failing", help: "The number of RSS feeds that hookshot is failing to read", labelNames: ["reason"], registers: [this.registry]}); - this.feedsCountDeprecated = new Gauge({ name: "feed_count", help: "(Deprecated) The number of RSS feeds that hookshot is subscribed to", labelNames: [], registers: [this.registry]}); - this.feedsFetchMsDeprecated = new Gauge({ name: "feed_fetch_ms", help: "(Deprecated) The time taken for hookshot to fetch all feeds", labelNames: [], registers: [this.registry]}); - this.feedsFailingDeprecated = new Gauge({ name: "feed_failing", help: "(Deprecated) The number of RSS feeds that hookshot is failing to read", labelNames: ["reason"], registers: [this.registry]}); + this.feedsCount = new Gauge({ name: "hookshot_feeds_count", help: "Number of RSS feeds that hookshot is subscribed to", labelNames: [], registers: [this.registry]}); + this.feedFetchMs = new Gauge({ name: "hookshot_feeds_fetch_ms", help: "Time taken for hookshot to fetch all feeds", labelNames: [], registers: [this.registry]}); + this.feedsFailing = new Gauge({ name: "hookshot_feeds_failing", help: "Number of RSS feeds that hookshot is failing to read", labelNames: ["reason"], registers: [this.registry]}); + this.feedsCountDeprecated = new Gauge({ name: "feed_count", help: "(Deprecated) Number of RSS feeds that hookshot is subscribed to", labelNames: [], registers: [this.registry]}); + this.feedsFetchMsDeprecated = new Gauge({ name: "feed_fetch_ms", help: "(Deprecated) Time taken for hookshot to fetch all feeds", labelNames: [], registers: [this.registry]}); + this.feedsFailingDeprecated = new Gauge({ name: "feed_failing", help: "(Deprecated) Number of RSS feeds that hookshot is failing to read", labelNames: ["reason"], registers: [this.registry]}); collectDefaultMetrics({ register: this.registry,