Inclusion in DB Console Dashboards

Oct 13, 2025 by wbrum.org 3 views

Motivation

In order to maintain a high level of quality and consistency in our metrics documentation, we need to introduce a subset of our metrics categorized as "Essential" with extended metadata and more controls around detailed usage instructions and descriptions. This will enable us to provide a better experience for our customers who are using integrations with Datadog or Prometheus. Currently, we document these metrics on our official website, but ideally, these docs should be generated from code much like our existing metrics documentation.

The existing documentation for essential metrics can be found at https://www.cockroachlabs.com/docs/stable/essential-metrics-self-hosted. However, maintaining this documentation manually can be time-consuming and prone to errors. By generating the documentation from code, we can ensure that it is always up-to-date and accurate.

Proposed Design

To achieve this, we propose adding more fields to the metric.Metadata struct to track whether the metric is "Essential" and enforce additional requirements. These requirements include:

Inclusion in DB Console Dashboards: Essential metrics should be included in the DB Console dashboards by default.
Inclusion of Description + Usage Data: Essential metrics should have a detailed description and usage instructions provided.
Optional Category: Essential metrics can be assigned a category to place them within a specific dashboard.

This additional metadata will be emitted to a separate doc under /docs/generated/metrics/ which contains just the essential metrics with extended metadata. This will make docs and dashboard maintenance easier.

Benefits

The proposed design offers several benefits, including:

Improved Documentation: By generating the documentation from code, we can ensure that it is always up-to-date and accurate.
Simplified Maintenance: With the additional metadata, we can easily maintain the documentation and dashboard metrics.
Enhanced Customer Experience: By providing a better experience for our customers who are using integrations with Datadog or Prometheus, we can improve their overall satisfaction with our product.

Implementation

To implement this design, we will need to make the following changes:

Update the metric.Metadata struct: Add the new fields to track whether the metric is "Essential" and enforce the additional requirements.
Generate the documentation: Use the additional metadata to generate the documentation for essential metrics.
Update the DB Console dashboards: Include the essential metrics in the DB Console dashboards by default.
Update the UI code: Use the generated documentation to intersect with the set of dashboard metrics in the UI code to determine if we have any gaps.

Conclusion

In conclusion, adding metadata definitions for "essential" metrics and exporting structured docs will improve the quality and consistency of our metrics documentation. By generating the documentation from code, we can ensure that it is always up-to-date and accurate. The proposed design offers several benefits, including improved documentation, simplified maintenance, and an enhanced customer experience. We believe that this design will have a positive impact on our product and our customers.

Jira Issue

The Jira issue associated with this design is CRDB-48425.

Future Work

In the future, we can consider adding more features to the metric.Metadata struct, such as:

Support for multiple categories: Allow essential metrics to be assigned multiple categories.
Customizable dashboard inclusion: Allow users to customize which essential metrics are included in the DB Console dashboards.
Integration with other tools: Integrate the essential metrics with other tools and services, such as Datadog or Prometheus.

Q&A

Q: What is the purpose of categorizing metrics as "Essential"?

A: The purpose of categorizing metrics as "Essential" is to provide a subset of our metrics with extended metadata and more controls around detailed usage instructions and descriptions. This will enable us to provide a better experience for our customers who are using integrations with Datadog or Prometheus.

Q: Why is it necessary to generate the documentation from code?

A: Generating the documentation from code ensures that it is always up-to-date and accurate. This is particularly important for metrics documentation, as it can change frequently. By generating the documentation from code, we can ensure that it is always consistent and accurate.

Q: What are the benefits of including essential metrics in the DB Console dashboards?

A: Including essential metrics in the DB Console dashboards provides several benefits, including:

Improved visibility: Essential metrics are more visible to users, making it easier for them to monitor and troubleshoot their applications.
Simplified maintenance: With essential metrics included in the DB Console dashboards, maintenance is simplified, as users can easily access and monitor the metrics they need.
Enhanced customer experience: By providing a better experience for our customers, we can improve their overall satisfaction with our product.

Q: How will the additional metadata be used?

A: The additional metadata will be used to generate the documentation for essential metrics. This documentation will be emitted to a separate doc under /docs/generated/metrics/ which contains just the essential metrics with extended metadata.

Q: What is the Jira issue associated with this design?

A: The Jira issue associated with this design is CRDB-48425.

Q: What are the future work items for this design?

A: Some potential future work items for this design include:

Support for multiple categories: Allow essential metrics to be assigned multiple categories.
Customizable dashboard inclusion: Allow users to customize which essential metrics are included in the DB Console dashboards.
Integration with other tools: Integrate the essential metrics with other tools and services, such as Datadog or Prometheus.

Additional Resources

For more information on this design, please refer to the following resources:

Existing documentation: The existing documentation for essential metrics can be found at https://www.cockroachlabs.com/docs/stable/essential-metrics-self-hosted.
Jira issue: The Jira issue associated with this design is CRDB-48425.