Skip to content

Commit c0a0bb6

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #2568 from Kavinjsir/feat/docs-metrics
📖 Add metrics references.
2 parents 6d59caf + b5b2d35 commit c0a0bb6

File tree

4 files changed

+40
-11
lines changed

4 files changed

+40
-11
lines changed

‎docs/book/src/SUMMARY.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,9 @@
9696
- [Configuring EnvTest](./reference/envtest.md)
9797

9898
- [Metrics](./reference/metrics.md)
99+
100+
- [Reference](./reference/metrics-reference.md)
101+
99102
- [Makefile Helpers](./reference/makefile-helpers.md)
100103
- [Project config](./reference/project-config.md)
101104

@@ -112,4 +115,4 @@
112115
[Appendix: The TODO Landing Page](./TODO.md)
113116

114117

115-
[plugins]: ./plugins/plugins.md
118+
[plugins]: ./plugins/plugins.md

‎docs/book/src/reference/metrics-reference.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Default Exported Metrics References
2+
3+
Following the metrics which are exported and provided by [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) by default:
4+
5+
| Metrics name | Type | Description |
6+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7+
| [workqueue_depth](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/metrics/workqueue.go#L41) | Gauge | Current depth of workqueue. |
8+
| [workqueue_adds_total](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/metrics/workqueue.go#L47) | Counter | Total number of adds handled by workqueue. |
9+
| [workqueue_queue_duration_seconds](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/metrics/workqueue.go#L53) | Histogram | How long in seconds an item stays in workqueue before being requested. |
10+
| [workqueue_work_duration_seconds](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/metrics/workqueue.go#L60) | Histogram | How long in seconds processing an item from workqueue takes. |
11+
| [workqueue_unfinished_work_seconds](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/metrics/workqueue.go#L67) | Gauge | How many seconds of work has been done that is in progress and hasn't been observed by work_duration. Large values indicate stuck threads. One can deduce the number of stuck threads by observing the rate at which this increases. |
12+
| [workqueue_longest_running_processor_seconds](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/metrics/workqueue.go#L76) | Gauge | How many seconds has the longest running processor for workqueue been running. |
13+
| [workqueue_retries_total](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/metrics/workqueue.go#L83) | Counter | Total number of retries handled by workqueue. |
14+
| [rest_client_requests_total ](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/metrics/client_go_adapter.go#L79) | Counter | Number of HTTP requests, partitioned by status code, method, and host. |
15+
| [controller_runtime_reconcile_total ](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/internal/controller/metrics/metrics.go#L30) | Counter | Total number of reconciliations per controller. |
16+
| [controller_runtime_reconcile_errors_total ](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/internal/controller/metrics/metrics.go#L37) | Counter | Total number of reconciliation errors per controller. |
17+
| [controller_runtime_reconcile_time_seconds ](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/internal/controller/metrics/metrics.go#L44) | Histogram | Length of time per reconciliation per controller. |
18+
| [controller_runtime_max_concurrent_reconciles ](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/internal/controller/metrics/metrics.go#L53) | Gauge | Maximum number of concurrent reconciles per controller. |
19+
| [controller_runtime_active_workers ](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/internal/controller/metrics/metrics.go#L60) | Gauge | Number of currently used workers per controller. |
20+
| [controller_runtime_webhook_latency_seconds ](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/webhook/internal/metrics/metrics.go#L31) | Histogram | Histogram of the latency of processing admission requests. |
21+
| [controller_runtime_webhook_requests_total ](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/webhook/internal/metrics/metrics.go#L40) | Counter | Total number of admission requests by HTTP status code. |
22+
| [controller_runtime_webhook_requests_in_flight](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.11.0/pkg/webhook/internal/metrics/metrics.go#L51) | Gauge | Current number of admission requests being served. |

‎docs/book/src/reference/metrics.md

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Metrics
22

33
By default, controller-runtime builds a global prometheus registry and
4-
publishes a collection of performance metrics for each controller.
4+
publishes [a collection of performance metrics](/reference/metrics-reference.md) for each controller.
55

66
## Protecting the Metrics
77

@@ -12,9 +12,10 @@ can be found at `config/rbac/auth_proxy_client_clusterrole.yaml`.
1212
You will need to grant permissions to your Prometheus server so that it can
1313
scrape the protected metrics. To achieve that, you can create a
1414
`clusterRoleBinding` to bind the `clusterRole` to the service account that your
15-
Prometheus server uses. If you are using `kube-prometheus`, this cluster binding already exists.
15+
Prometheus server uses. If you are using [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus),
16+
this cluster binding already exists.
1617

17-
You can either run the following command, or apply the example yaml file provided below to create `clusterRoleBinding`.
18+
You can either run the following command, or apply the example yaml file provided below to create `clusterRoleBinding`.
1819

1920
If using kubebuilder
2021
`<project-prefix>` is the `namePrefix` field in `config/default/kustomization.yaml`.
@@ -24,6 +25,7 @@ kubectl create clusterrolebinding metrics --clusterrole=<project-prefix>-metrics
2425
```
2526

2627
You can also apply the following `ClusterRoleBinding`:
28+
2729
```yaml
2830
apiVersion: rbac.authorization.k8s.io/v1
2931
kind: ClusterRoleBinding
@@ -38,18 +40,19 @@ subjects:
3840
name: <prometheus-service-account>
3941
namespace: <prometheus-service-account-namespace>
4042
```
43+
4144
The `prometheus-k8s-role` referenced here should provide the necessary permissions to allow prometheus scrape metrics from operator pods.
4245

4346
## Exporting Metrics for Prometheus
4447

4548
Follow the steps below to export the metrics using the Prometheus Operator:
4649

4750
1. Install Prometheus and Prometheus Operator.
48-
We recommend using [kube-prometheus](https://github.com/coreos/kube-prometheus#installing)
49-
in production if you don't have your own monitoring system.
50-
If you are just experimenting, you can only install Prometheus and Prometheus Operator.
51+
We recommend using [kube-prometheus](https://github.com/coreos/kube-prometheus#installing)
52+
in production if you don't have your own monitoring system.
53+
If you are just experimenting, you can only install Prometheus and Prometheus Operator.
5154
2. Uncomment the line `- ../prometheus` in the `config/default/kustomization.yaml`.
52-
It creates the `ServiceMonitor` resource which enables exporting the metrics.
55+
It creates the `ServiceMonitor` resource which enables exporting the metrics.
5356

5457
```yaml
5558
# [PROMETHEUS] To enable prometheus monitor, uncomment all sections with 'PROMETHEUS'.
@@ -116,13 +119,11 @@ reconcile loop. These metrics can be evaluated from anywhere in the operator cod
116119
<aside class="note">
117120
<h2>Enabling metrics in Prometheus UI</h1>
118121

119-
In order to publish metrics and view them on the Prometheus UI, the Prometheus instance would have to be configured to select the Service Monitor instance based on its labels.
122+
In order to publish metrics and view them on the Prometheus UI, the Prometheus instance would have to be configured to select the Service Monitor instance based on its labels.
120123

121124
</aside>
122125

123126
Those metrics will be available for prometheus or
124127
other openmetrics systems to scrape.
125128

126129
![Screen Shot 2021-06-14 at 10 15 59 AM](https://user-images.githubusercontent.com/37827279/121932262-8843cd80-ccf9-11eb-9c8e-98d0eda80169.png)
127-
128-

‎docs/book/src/reference/reference.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,5 +32,8 @@
3232
- [Artifacts](artifacts.md)
3333
- [Writing controller tests](writing-tests.md)
3434
- [Metrics](metrics.md)
35+
36+
- [Reference](metrics-reference.md)
37+
3538
- [Makefile Helpers](makefile-helpers.md)
3639
- [CLI plugins](../plugins/cli-plugins.md)

0 commit comments

Comments
 (0)