From e6fba93a1411aee510f57015ce31a8aa62dfd1b3 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 7 Nov 2025 19:07:29 +0100 Subject: [PATCH] docs: document provider.provides metric rename Update documentation for metric rename from total_provide_count_total to provider_provides_total (following OpenTelemetry naming conventions). - update metrics.md with new metric name - add v0.39 changelog entry with migration guidance - add v0.38 warnings about the upcoming rename See: https://github.com/libp2p/go-libp2p-kad-dht/pull/1195 --- docs/changelogs/v0.38.md | 6 ++++++ docs/changelogs/v0.39.md | 9 +++++++++ docs/examples/kubo-as-a-library/go.mod | 2 +- docs/examples/kubo-as-a-library/go.sum | 4 ++-- docs/metrics.md | 2 +- go.mod | 2 +- go.sum | 4 ++-- test/dependencies/go.mod | 2 +- test/dependencies/go.sum | 4 ++-- test/sharness/t0119-prometheus-data/prometheus_metrics | 2 +- 10 files changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/changelogs/v0.38.md b/docs/changelogs/v0.38.md index 842479794..f76667239 100644 --- a/docs/changelogs/v0.38.md +++ b/docs/changelogs/v0.38.md @@ -59,6 +59,9 @@ A new experimental DHT provider is available as an alternative to both the defau **Monitoring and debugging:** Legacy mode (`SweepEnabled=false`) tracks `provider_reprovider_provide_count` and `provider_reprovider_reprovide_count`, while sweep mode (`SweepEnabled=true`) tracks `total_provide_count_total`. Enable debug logging with `GOLOG_LOG_LEVEL=error,provider=debug,dht/provider=debug` to see detailed logs from either system. +> [!IMPORTANT] +> The metric `total_provide_count_total` was renamed to `provider_provides_total` in Kubo v0.39 to follow OpenTelemetry naming conventions. If you have dashboards or alerts monitoring this metric, update them accordingly. + > [!NOTE] > This feature is experimental and opt-in. In the future, it will become the default and replace the legacy system. Some commands like `ipfs stats provide` and `ipfs routing provide` are not yet available with sweep mode. Run `ipfs provide --help` for alternatives. @@ -68,6 +71,9 @@ For configuration details, see [`Provide.DHT`](https://github.com/ipfs/kubo/blob Kubo now exposes DHT metrics from [go-libp2p-kad-dht](https://github.com/libp2p/go-libp2p-kad-dht/), including `total_provide_count_total` for sweep provider operations and RPC metrics prefixed with `rpc_inbound_` and `rpc_outbound_` for DHT message traffic. See [Kubo metrics documentation](https://github.com/ipfs/kubo/blob/master/docs/metrics.md) for details. +> [!IMPORTANT] +> The metric `total_provide_count_total` was renamed to `provider_provides_total` in Kubo v0.39 to follow OpenTelemetry naming conventions. If you have dashboards or alerts monitoring this metric, update them accordingly. + #### ðŸšĻ Improved gateway error pages with diagnostic tools Gateway error pages now provide more actionable information during content retrieval failures. When a 504 Gateway Timeout occurs, users see detailed retrieval state information including which phase failed and a sample of providers that were attempted: diff --git a/docs/changelogs/v0.39.md b/docs/changelogs/v0.39.md index 90e9eb8e8..78781f39f 100644 --- a/docs/changelogs/v0.39.md +++ b/docs/changelogs/v0.39.md @@ -13,6 +13,7 @@ This release was brought to you by the [Shipyard](https://ipshipyard.com/) team. - [📊 Detailed statistics for Sweep provider with `ipfs provide stat`](#-detailed-statistics-for-sweep-provider-with-ipfs-provide-stat) - [âŊïļ Provider resume cycle for improved reproviding reliability](#provider-resume-cycle-for-improved-reproviding-reliability) - [🔔 Sweep provider slow reprovide warnings](#-sweep-provider-slow-reprovide-warnings) + - [📊 Metric rename: `provider_provides_total`](#-metric-rename-provider_provides_total) - [🔧 Fixed UPnP port forwarding after router restarts](#-fixed-upnp-port-forwarding-after-router-restarts) - [ðŸ–Ĩïļ RISC-V support with prebuilt binaries](#ïļ-risc-v-support-with-prebuilt-binaries) - [ðŸŠĶ Deprecated `go-ipfs` name no longer published](#-deprecated-go-ipfs-name-no-longer-published) @@ -105,6 +106,14 @@ The alert polls every 15 minutes (to avoid alert fatigue while catching persistent issues) and only triggers after sustained growth across multiple intervals. The legacy provider is unaffected by this change. +#### 📊 Metric rename: `provider_provides_total` + +The sweeping provider metric has been renamed from `total_provide_count_total` to `provider_provides_total` to follow OpenTelemetry naming conventions and maintain consistency with other kad-dht metrics (which use dot notation like `rpc.inbound.messages`, `rpc.outbound.requests`, etc.). + +**Migration:** If you have Prometheus queries, dashboards, or alerts monitoring the old `total_provide_count_total` metric, update them to use `provider_provides_total` instead. + +This change only affects users who enabled the experimental sweeping provider in v0.38 via `Provide.DHT.SweepEnabled=true`. + #### 🔧 Fixed UPnP port forwarding after router restarts Kubo now automatically recovers UPnP port mappings when routers restart or diff --git a/docs/examples/kubo-as-a-library/go.mod b/docs/examples/kubo-as-a-library/go.mod index a517c3854..017abab4e 100644 --- a/docs/examples/kubo-as-a-library/go.mod +++ b/docs/examples/kubo-as-a-library/go.mod @@ -115,7 +115,7 @@ require ( github.com/libp2p/go-doh-resolver v0.5.0 // indirect github.com/libp2p/go-flow-metrics v0.3.0 // indirect github.com/libp2p/go-libp2p-asn-util v0.4.1 // indirect - github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251101210821-a53fc23f77f4 // indirect + github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251107175014-3fa0f96d4ec8 // indirect github.com/libp2p/go-libp2p-kbucket v0.8.0 // indirect github.com/libp2p/go-libp2p-pubsub v0.14.2 // indirect github.com/libp2p/go-libp2p-pubsub-router v0.6.0 // indirect diff --git a/docs/examples/kubo-as-a-library/go.sum b/docs/examples/kubo-as-a-library/go.sum index 3add9e5d4..ab56147cf 100644 --- a/docs/examples/kubo-as-a-library/go.sum +++ b/docs/examples/kubo-as-a-library/go.sum @@ -430,8 +430,8 @@ github.com/libp2p/go-libp2p-asn-util v0.4.1 h1:xqL7++IKD9TBFMgnLPZR6/6iYhawHKHl9 github.com/libp2p/go-libp2p-asn-util v0.4.1/go.mod h1:d/NI6XZ9qxw67b4e+NgpQexCIiFYJjErASrYW4PFDN8= github.com/libp2p/go-libp2p-core v0.2.4/go.mod h1:STh4fdfa5vDYr0/SzYYeqnt+E6KfEV5VxfIrm0bcI0g= github.com/libp2p/go-libp2p-core v0.3.0/go.mod h1:ACp3DmS3/N64c2jDzcV429ukDpicbL6+TrrxANBjPGw= -github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251101210821-a53fc23f77f4 h1:WZ+J++OumrLYNRmlUHKR9Ibpd7aoNv8u/ttbzP+0PNg= -github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251101210821-a53fc23f77f4/go.mod h1:WIysu8hNWQN8t73dKyTNqiZdcYKRrGFl4wjzX4Gz6pQ= +github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251107175014-3fa0f96d4ec8 h1:euwpK5JfXcSy18L0mHeWlEjFLR9qyaEVCgxOBiCeUFg= +github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251107175014-3fa0f96d4ec8/go.mod h1:xcaCnUDRpedsVg4AAYUwx/eG0jooprOkmwUXbdNRUo4= github.com/libp2p/go-libp2p-kbucket v0.3.1/go.mod h1:oyjT5O7tS9CQurok++ERgc46YLwEpuGoFq9ubvoUOio= github.com/libp2p/go-libp2p-kbucket v0.8.0 h1:QAK7RzKJpYe+EuSEATAaaHYMYLkPDGC18m9jxPLnU8s= github.com/libp2p/go-libp2p-kbucket v0.8.0/go.mod h1:JMlxqcEyKwO6ox716eyC0hmiduSWZZl6JY93mGaaqc4= diff --git a/docs/metrics.md b/docs/metrics.md index 548359694..fe684cbc6 100644 --- a/docs/metrics.md +++ b/docs/metrics.md @@ -59,7 +59,7 @@ Metrics for the legacy provider system when `Provide.DHT.SweepEnabled=false`: Metrics for the DHT provider system when `Provide.DHT.SweepEnabled=true`: -- `total_provide_count_total` - Counter: total successful provide operations since node startup (includes both one-time provides and periodic provides done on `Provide.DHT.Interval`) +- `provider_provides_total` - Counter: total successful provide operations since node startup (includes both one-time provides and periodic provides done on `Provide.DHT.Interval`) > [!NOTE] > These metrics are exposed by [go-libp2p-kad-dht](https://github.com/libp2p/go-libp2p-kad-dht/). You can enable debug logging for DHT provider activity with `GOLOG_LOG_LEVEL=dht/provider=debug`. diff --git a/go.mod b/go.mod index e2c9367ae..8eb102634 100644 --- a/go.mod +++ b/go.mod @@ -53,7 +53,7 @@ require ( github.com/libp2p/go-doh-resolver v0.5.0 github.com/libp2p/go-libp2p v0.45.0 github.com/libp2p/go-libp2p-http v0.5.0 - github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251101210821-a53fc23f77f4 + github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251107175014-3fa0f96d4ec8 github.com/libp2p/go-libp2p-kbucket v0.8.0 github.com/libp2p/go-libp2p-pubsub v0.14.2 github.com/libp2p/go-libp2p-pubsub-router v0.6.0 diff --git a/go.sum b/go.sum index c37f037c9..bb0d07a87 100644 --- a/go.sum +++ b/go.sum @@ -514,8 +514,8 @@ github.com/libp2p/go-libp2p-gostream v0.6.0 h1:QfAiWeQRce6pqnYfmIVWJFXNdDyfiR/qk github.com/libp2p/go-libp2p-gostream v0.6.0/go.mod h1:Nywu0gYZwfj7Jc91PQvbGU8dIpqbQQkjWgDuOrFaRdA= github.com/libp2p/go-libp2p-http v0.5.0 h1:+x0AbLaUuLBArHubbbNRTsgWz0RjNTy6DJLOxQ3/QBc= github.com/libp2p/go-libp2p-http v0.5.0/go.mod h1:glh87nZ35XCQyFsdzZps6+F4HYI6DctVFY5u1fehwSg= -github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251101210821-a53fc23f77f4 h1:WZ+J++OumrLYNRmlUHKR9Ibpd7aoNv8u/ttbzP+0PNg= -github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251101210821-a53fc23f77f4/go.mod h1:WIysu8hNWQN8t73dKyTNqiZdcYKRrGFl4wjzX4Gz6pQ= +github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251107175014-3fa0f96d4ec8 h1:euwpK5JfXcSy18L0mHeWlEjFLR9qyaEVCgxOBiCeUFg= +github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251107175014-3fa0f96d4ec8/go.mod h1:xcaCnUDRpedsVg4AAYUwx/eG0jooprOkmwUXbdNRUo4= github.com/libp2p/go-libp2p-kbucket v0.3.1/go.mod h1:oyjT5O7tS9CQurok++ERgc46YLwEpuGoFq9ubvoUOio= github.com/libp2p/go-libp2p-kbucket v0.8.0 h1:QAK7RzKJpYe+EuSEATAaaHYMYLkPDGC18m9jxPLnU8s= github.com/libp2p/go-libp2p-kbucket v0.8.0/go.mod h1:JMlxqcEyKwO6ox716eyC0hmiduSWZZl6JY93mGaaqc4= diff --git a/test/dependencies/go.mod b/test/dependencies/go.mod index cd1d1893e..d59f69b0d 100644 --- a/test/dependencies/go.mod +++ b/test/dependencies/go.mod @@ -184,7 +184,7 @@ require ( github.com/libp2p/go-flow-metrics v0.3.0 // indirect github.com/libp2p/go-libp2p v0.45.0 // indirect github.com/libp2p/go-libp2p-asn-util v0.4.1 // indirect - github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251101210821-a53fc23f77f4 // indirect + github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251107175014-3fa0f96d4ec8 // indirect github.com/libp2p/go-libp2p-kbucket v0.8.0 // indirect github.com/libp2p/go-libp2p-record v0.3.1 // indirect github.com/libp2p/go-libp2p-routing-helpers v0.7.5 // indirect diff --git a/test/dependencies/go.sum b/test/dependencies/go.sum index f2573a28d..7bb6a8cbc 100644 --- a/test/dependencies/go.sum +++ b/test/dependencies/go.sum @@ -464,8 +464,8 @@ github.com/libp2p/go-libp2p v0.45.0 h1:Pdhr2HsFXaYjtfiNcBP4CcRUONvbMFdH3puM9vV4T github.com/libp2p/go-libp2p v0.45.0/go.mod h1:NovCojezAt4dnDd4fH048K7PKEqH0UFYYqJRjIIu8zc= github.com/libp2p/go-libp2p-asn-util v0.4.1 h1:xqL7++IKD9TBFMgnLPZR6/6iYhawHKHl950SO9L6n94= github.com/libp2p/go-libp2p-asn-util v0.4.1/go.mod h1:d/NI6XZ9qxw67b4e+NgpQexCIiFYJjErASrYW4PFDN8= -github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251101210821-a53fc23f77f4 h1:WZ+J++OumrLYNRmlUHKR9Ibpd7aoNv8u/ttbzP+0PNg= -github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251101210821-a53fc23f77f4/go.mod h1:WIysu8hNWQN8t73dKyTNqiZdcYKRrGFl4wjzX4Gz6pQ= +github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251107175014-3fa0f96d4ec8 h1:euwpK5JfXcSy18L0mHeWlEjFLR9qyaEVCgxOBiCeUFg= +github.com/libp2p/go-libp2p-kad-dht v0.35.2-0.20251107175014-3fa0f96d4ec8/go.mod h1:xcaCnUDRpedsVg4AAYUwx/eG0jooprOkmwUXbdNRUo4= github.com/libp2p/go-libp2p-kbucket v0.8.0 h1:QAK7RzKJpYe+EuSEATAaaHYMYLkPDGC18m9jxPLnU8s= github.com/libp2p/go-libp2p-kbucket v0.8.0/go.mod h1:JMlxqcEyKwO6ox716eyC0hmiduSWZZl6JY93mGaaqc4= github.com/libp2p/go-libp2p-record v0.3.1 h1:cly48Xi5GjNw5Wq+7gmjfBiG9HCzQVkiZOUZ8kUl+Fg= diff --git a/test/sharness/t0119-prometheus-data/prometheus_metrics b/test/sharness/t0119-prometheus-data/prometheus_metrics index 03d56bb2e..1099032d7 100644 --- a/test/sharness/t0119-prometheus-data/prometheus_metrics +++ b/test/sharness/t0119-prometheus-data/prometheus_metrics @@ -250,5 +250,5 @@ process_resident_memory_bytes process_start_time_seconds process_virtual_memory_bytes process_virtual_memory_max_bytes +provider_provides_total target_info -total_provide_count_total