From 1cde29f9f87aa84665aa44bdd150af2e5bf3fb67 Mon Sep 17 00:00:00 2001 From: Victor Rodriguez Date: Tue, 15 Feb 2022 11:04:21 -0500 Subject: [PATCH] Restore tidy-status documentation. (#14075) Restore tidy-status documentation. Fixes VAULT-5113. --- website/content/api-docs/secret/pki.mdx | 50 +++++++++++++++++ website/content/docs/internals/telemetry.mdx | 58 ++++++++++++-------- 2 files changed, 84 insertions(+), 24 deletions(-) diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index 1bb0531ad6..beb961bb81 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki.mdx @@ -43,6 +43,7 @@ update your API calls accordingly. - [Sign Certificate](#sign-certificate) - [Sign Verbatim](#sign-verbatim) - [Tidy](#tidy) +- [Tidy Status](#tidy-status) - [Managed Key](#managed-keys) (Enterprise Only) ## Read CA Certificate @@ -1671,6 +1672,55 @@ $ curl \ http://127.0.0.1:8200/v1/pki/tidy ``` +## Tidy Status + +This is a read only endpoint that returns information about the current tidy +operation, or the most recent if none are currently running. + +The result includes the following fields: +* `safety_buffer`: the value of this parameter when initiating the tidy operation +* `tidy_cert_store`: the value of this parameter when initiating the tidy operation +* `tidy_revoked_certs`: the value of this parameter when initiating the tidy operation +* `state`: one of *Inactive*, *Running*, *Finished*, *Error* +* `error`: the error message, if the operation ran into an error +* `time_started`: the time the operation started +* `time_finished`: the time the operation finished +* `message`: One of *Tidying certificate store: checking entry N of TOTAL* or + *Tidying revoked certificates: checking certificate N of TOTAL* +* `cert_store_deleted_count`: The number of certificate storage entries deleted +* `revoked_cert_deleted_count`: The number of revoked certificate entries deleted + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/pki/tidy-status` | + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/pki/tidy-status + +``` + +### Sample Response + +```json + "data": { + "safety_buffer": 60, + "tidy_cert_store": true, + "tidy_revoked_certs": true, + "error": null, + "message": "Tidying certificate store: checking entry 234 of 488", + "revoked_cert_deleted_count": 0, + "cert_store_deleted_count": 2, + "state": "Running", + "time_started": "2021-10-20T14:52:13.510161-04:00", + "time_finished": null + }, +``` + # Cluster Scalability Most non-introspection operations in the PKI secrets engine require a write to diff --git a/website/content/docs/internals/telemetry.mdx b/website/content/docs/internals/telemetry.mdx index 8ffec71275..a0061af62c 100644 --- a/website/content/docs/internals/telemetry.mdx +++ b/website/content/docs/internals/telemetry.mdx @@ -289,30 +289,40 @@ These metrics relate to [Vault Enterprise Replication](/docs/enterprise/replicat These metrics relate to the supported [secrets engines][secrets-engines]. -| Metric | Description | Unit | Type | -| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | :------ | -| `database.Initialize` | Time taken to initialize a database secret engine across all database secrets engines | ms | summary | -| `database..Initialize` | Time taken to initialize a database secret engine for the named database secrets engine ``, for example: `database.postgresql-prod.Initialize` | ms | summary | -| `database.Initialize.error` | Number of database secrets engine initialization operation errors across all database secrets engines | errors | counter | -| `database..Initialize.error` | Number of database secrets engine initialization operation errors for the named database secrets engine ``, for example: `database.postgresql-prod.Initialize.error` | errors | counter | -| `database.Close` | Time taken to close a database secret engine across all database secrets engines | ms | summary | -| `database..Close` | Time taken to close a database secret engine for the named database secrets engine ``, for example: `database.postgresql-prod.Close` | ms | summary | -| `database.Close.error` | Number of database secrets engine close operation errors across all database secrets engines | errors | counter | -| `database..Close.error` | Number of database secrets engine close operation errors for the named database secrets engine ``, for example: `database.postgresql-prod.Close.error` | errors | counter | -| `database.CreateUser` | Time taken to create a user across all database secrets engines | ms | summary | -| `database..CreateUser` | Time taken to create a user for the named database secrets engine `` | ms | summary | -| `database.CreateUser.error` | Number of user creation operation errors across all database secrets engines | errors | counter | -| `database..CreateUser.error` | Number of user creation operation errors for the named database secrets engine ``, for example: `database.postgresql-prod.CreateUser.error` | errors | counter | -| `database.RenewUser` | Time taken to renew a user across all database secrets engines | ms | summary | -| `database..RenewUser` | Time taken to renew a user for the named database secrets engine ``, for example: `database.postgresql-prod.RenewUser` | ms | summary | -| `database.RenewUser.error` | Number of user renewal operation errors across all database secrets engines | errors | counter | -| `database..RenewUser.error` | Number of user renewal operations for the named database secrets engine ``, for example: `database.postgresql-prod.RenewUser.error` | errors | counter | -| `database.RevokeUser` | Time taken to revoke a user across all database secrets engines | ms | summary | -| `database..RevokeUser` | Time taken to revoke a user for the named database secrets engine ``, for example: `database.postgresql-prod.RevokeUser` | ms | summary | -| `database.RevokeUser.error` | Number of user revocation operation errors across all database secrets engines | errors | counter | -| `database..RevokeUser.error` | Number of user revocation operations for the named database secrets engine ``, for example: `database.postgresql-prod.RevokeUser.error` | errors | counter | -| `vault.secret.kv.count` (cluster, namespace, mount_point) | Number of entries in each key-value secret engine. | paths | gauge | -| `vault.secret.lease.creation` (cluster, namespace, secret_engine, mount_point, creation_ttl) | Counts the number of leases created by secret engines. | leases | counter | +| Metric | Description | Unit | Type | +| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- | :------ | +| `database.Initialize` | Time taken to initialize a database secret engine across all database secrets engines | ms | summary | +| `database..Initialize` | Time taken to initialize a database secret engine for the named database secrets engine ``, for example: `database.postgresql-prod.Initialize` | ms | summary | +| `database.Initialize.error` | Number of database secrets engine initialization operation errors across all database secrets engines | errors | counter | +| `database..Initialize.error` | Number of database secrets engine initialization operation errors for the named database secrets engine ``, for example: `database.postgresql-prod.Initialize.error` | errors | counter | +| `database.Close` | Time taken to close a database secret engine across all database secrets engines | ms | summary | +| `database..Close` | Time taken to close a database secret engine for the named database secrets engine ``, for example: `database.postgresql-prod.Close` | ms | summary | +| `database.Close.error` | Number of database secrets engine close operation errors across all database secrets engines | errors | counter | +| `database..Close.error` | Number of database secrets engine close operation errors for the named database secrets engine ``, for example: `database.postgresql-prod.Close.error` | errors | counter | +| `database.CreateUser` | Time taken to create a user across all database secrets engines | ms | summary | +| `database..CreateUser` | Time taken to create a user for the named database secrets engine `` | ms | summary | +| `database.CreateUser.error` | Number of user creation operation errors across all database secrets engines | errors | counter | +| `database..CreateUser.error` | Number of user creation operation errors for the named database secrets engine ``, for example: `database.postgresql-prod.CreateUser.error` | errors | counter | +| `database.RenewUser` | Time taken to renew a user across all database secrets engines | ms | summary | +| `database..RenewUser` | Time taken to renew a user for the named database secrets engine ``, for example: `database.postgresql-prod.RenewUser` | ms | summary | +| `database.RenewUser.error` | Number of user renewal operation errors across all database secrets engines | errors | counter | +| `database..RenewUser.error` | Number of user renewal operations for the named database secrets engine ``, for example: `database.postgresql-prod.RenewUser.error` | errors | counter | +| `database.RevokeUser` | Time taken to revoke a user across all database secrets engines | ms | summary | +| `database..RevokeUser` | Time taken to revoke a user for the named database secrets engine ``, for example: `database.postgresql-prod.RevokeUser` | ms | summary | +| `database.RevokeUser.error` | Number of user revocation operation errors across all database secrets engines | errors | counter | +| `database..RevokeUser.error` | Number of user revocation operations for the named database secrets engine ``, for example: `database.postgresql-prod.RevokeUser.error` | errors | counter | +| `secrets.pki.tidy.cert_store_current_entry` | The index of the current entry in the certificate store being verified by the tidy operation | entry index | gauge | +| `secrets.pki.tidy.cert_store_deleted_count` | Number of entries deleted from the certificate store | entry | counter | +| `secrets.pki.tidy.cert_store_total_entries` | Number of entries in the certificate store to verify during the tidy operation | entry | gauge | +| `secrets.pki.tidy.duration` | Duration of time taken by the PKI tidy operation | ms | summary | +| `secrets.pki.tidy.failure` | Number of times the PKI tidy operation has not completed due to errors | operations | counter | +| `secrets.pki.tidy.revoked_cert_current_entry` | The index of the current revoked certificate entry in the certificate store being verified by the tidy operation | entry index | gauge | +| `secrets.pki.tidy.revoked_cert_deleted_count` | Number of entries deleted from the certificate store for revoked certificates | entry | counter | +| `secrets.pki.tidy.revoked_cert_total_entries` | Number of entries in the certificate store for revoked certificates to verify during the tidy operation | entry | gauge | +| `secrets.pki.tidy.start_time_epoch` | Start time (as seconds since Jan 1 1970) when the PKI tidy operation is active, 0 otherwise | seconds | gauge | +| `secrets.pki.tidy.success` | Number of times the PKI tidy operation has completed succcessfully | operations | counter | +| `vault.secret.kv.count` (cluster, namespace, mount_point) | Number of entries in each key-value secret engine. | paths | gauge | +| `vault.secret.lease.creation` (cluster, namespace, secret_engine, mount_point, creation_ttl) | Counts the number of leases created by secret engines. | leases | counter | ## Storage Backend Metrics