prometheus: Document new behavior of unavailable or unknown entities #34632
Conversation
home-assistant
bot
added
has-parent
|
Warning Rate limit exceeded@agoode has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 3 minutes and 11 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 Walkthrough📝 Walkthrough📝 Walkthrough📝 WalkthroughWalkthroughThe pull request modifies the Prometheus exporter behavior regarding the export of metrics for entities in unavailable or unknown states. A new configuration attribute, Changes
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Outside diff range, codebase verification and nitpick comments (1)
source/_integrations/prometheus.markdown (1)
Line range hint
202-222: Clarification on behavior during unavailable or unknown states.The documentation provides a detailed explanation of how metrics are handled when entities are in unavailable or unknown states, depending on the
export_unavailable_metricssetting. The use of examples and the explanation of theentity_availablemetric are particularly helpful.However, there is a minor typographical error in line 202, where it states "are not be exported" which should be corrected to "are not exported". This will improve the clarity and professionalism of the documentation.
Please correct the typographical error:
- all non-excluded entities in an unavailable or unknown state are not be exported until they are available again. + all non-excluded entities in an unavailable or unknown state are not exported until they are available again.
agoode
force-pushed
the
nan
branch
5 times, most recently
from
8dfaab6
to
cbaefb3
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
Outside diff range and nitpick comments (1)
source/_integrations/prometheus.markdown (1)
Line range hint
203-226: Excellent explanation of the attribute's behavior! Address the minor grammar suggestions.The detailed explanation of how
export_unavailable_metricsaffects the behavior of metrics during unavailability is clear and comprehensive. It effectively covers both scenarios when the attribute is set totrueorfalse.The inclusion of the note indicating the upcoming change in the default value is also appreciated, as it keeps users informed about future changes.
Please address the following minor grammar suggestions:
Line 205: Add a comma after "unknown again" to improve readability.
-If the entity goes into state unavailable or unknown again, two things can happen depending on the state of the `export_unavailable_metrics` configuration attribute. +If the entity goes into state unavailable or unknown again, two things can happen, depending on the state of the `export_unavailable_metrics` configuration attribute.Line 226: Add a comma after "performant)" to separate the two independent clauses.
-When `export_unavailable_metrics` is false, then metrics will automatically be unexported when unavailable or unknown, and return again automatically when available and known. This makes it possible to write simpler (and more often performant) queries since there is no need to use `unless entity_available == 0` or a recording rule to filter out these metrics. +When `export_unavailable_metrics` is false, then metrics will automatically be unexported when unavailable or unknown, and return again automatically when available and known. This makes it possible to write simpler (and more often performant) queries, since there is no need to use `unless entity_available == 0` or a recording rule to filter out these metrics.Tools
LanguageTool
[uncategorized] ~205-~205: Possible missing comma found.
Context: ...ilable or unknown again, two things can happen depending on the state of the `export_u...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~215-~215: Possible missing comma found.
Context: ... entity is unavailable or in an unknown state thanks to a [recording rule](https://pr...(AI_HYDRA_LEO_MISSING_COMMA)
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (1)
- source/_integrations/prometheus.markdown (4 hunks)
Additional context used
LanguageTool
source/_integrations/prometheus.markdown
[uncategorized] ~205-~205: Possible missing comma found.
Context: ...ilable or unknown again, two things can happen depending on the state of the `export_u...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~226-~226: Possible missing comma found.
Context: ...ite simpler (and more often performant) queries since there is no need to use `unless e...(AI_HYDRA_LEO_MISSING_COMMA)
Additional comments not posted (3)
source/_integrations/prometheus.markdown (3)
72-76: ** Add a brief example to illustrate the attribute's usage.**The past review comment suggesting the addition of a brief example is still applicable. Here's the suggested example to include:
# Example configuration.yaml entry prometheus: export_unavailable_metrics: falseThis example can help users quickly understand how to implement the attribute without needing to search elsewhere in the document.
138-138: LGTM!The usage of
export_unavailable_metrics: falsein the advanced configuration example is correct and consistent with the attribute's documentation.
228-232: LGTM!The example configuration setting
export_unavailable_metrics: falseis correct and consistent with the attribute's documentation.
There was a problem hiding this comment.
Actionable comments posted: 1
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files selected for processing (1)
- source/_integrations/prometheus.markdown (4 hunks)
Additional context used
LanguageTool
source/_integrations/prometheus.markdown
[uncategorized] ~205-~205: Possible missing comma found.
Context: ...ilable or unknown again, two things can happen depending on the state of the `export_u...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~226-~226: Possible missing comma found.
Context: ...ite simpler (and more often performant) queries since there is no need to use `unless e...(AI_HYDRA_LEO_MISSING_COMMA)
Additional comments not posted (4)
source/_integrations/prometheus.markdown (4)
72-76: Documentation for the new attribute is clear and comprehensive.The documentation effectively explains the behavior of the
export_unavailable_metricsattribute when set totrueorfalse, and clearly states the default value.As suggested in the previous review, consider adding a brief example to illustrate the attribute's usage in a
configuration.yamlfile. This can help users quickly understand how to implement it.For example:
# Example configuration.yaml entry prometheus: export_unavailable_metrics: false
138-138: The advanced configuration example correctly demonstrates settingexport_unavailable_metricstofalse.The example aligns with the attribute's documentation and provides a practical demonstration of its usage.
203-209: The explanation provides important context and effectively introduces theexport_unavailable_metricsattribute.The documentation clearly explains the default behavior of metrics for unavailable or unknown entities and how the
export_unavailable_metricsattribute impacts the export behavior.The note about the upcoming change in the default value is crucial for users to be aware of and plan accordingly.
Tools
LanguageTool
[uncategorized] ~205-~205: Possible missing comma found.
Context: ...ilable or unknown again, two things can happen depending on the state of the `export_u...(AI_HYDRA_LEO_MISSING_COMMA)
Line range hint
211-223: The explanation clearly describes the behavior whenexport_unavailable_metricsis set totrue.The documentation provides important information about the
entity_availablemetric and its usage to indicate when an entity is unavailable or unknown.The example of using a recording rule to filter out values is helpful for users to understand how to handle metrics for unavailable or unknown entities.
Tools
LanguageTool
[uncategorized] ~205-~205: Possible missing comma found.
Context: ...ilable or unknown again, two things can happen depending on the state of the `export_u...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~215-~215: Possible missing comma found.
Context: ... entity is unavailable or in an unknown state thanks to a [recording rule](https://pr...(AI_HYDRA_LEO_MISSING_COMMA)
| ### `export_unavailable_metrics: false` | ||
|
|
||
| When `export_unavailable_metrics` is false, then metrics will automatically be unexported when unavailable or unknown, and return again automatically when available and known. This makes it possible to write simpler (and more often performant) queries since there is no need to use `unless entity_available == 0` or a recording rule to filter out these metrics. | ||
|
|
||
| ```yaml | ||
| # Example configuration.yaml entry | ||
| prometheus: | ||
| export_unavailable_metrics: false | ||
| ``` | ||
|
|
There was a problem hiding this comment.
The explanation clearly describes the behavior and benefits when export_unavailable_metrics is set to false.
The documentation effectively highlights the advantages of using this setting, such as simpler queries and improved performance by automatically unexporting and re-exporting metrics based on entity availability.
The example configuration is helpful for users to understand how to set the attribute to false.
Consider adding the missing commas as indicated by the static analysis hints:
-When `export_unavailable_metrics` is false, then metrics will automatically be unexported when unavailable or unknown, and return again automatically when available and known.
+When `export_unavailable_metrics` is false, then metrics will automatically be unexported when unavailable or unknown, and return again automatically when available and known.
-This makes it possible to write simpler (and more often performant) queries since there is no need to use `unless entity_available == 0` or a recording rule to filter out these metrics.
+This makes it possible to write simpler (and more often performant) queries, since there is no need to use `unless entity_available == 0` or a recording rule to filter out these metrics.Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### `export_unavailable_metrics: false` | |
| When `export_unavailable_metrics` is false, then metrics will automatically be unexported when unavailable or unknown, and return again automatically when available and known. This makes it possible to write simpler (and more often performant) queries since there is no need to use `unless entity_available == 0` or a recording rule to filter out these metrics. | |
| ```yaml | |
| # Example configuration.yaml entry | |
| prometheus: | |
| export_unavailable_metrics: false | |
| ``` | |
| ### `export_unavailable_metrics: false` | |
| When `export_unavailable_metrics` is false, then metrics will automatically be unexported when unavailable or unknown, and return again automatically when available and known. | |
| This makes it possible to write simpler (and more often performant) queries, since there is no need to use `unless entity_available == 0` or a recording rule to filter out these metrics. | |
| ```yaml | |
| # Example configuration.yaml entry | |
| prometheus: | |
| export_unavailable_metrics: false | |
| ``` |
Tools
LanguageTool
[uncategorized] ~226-~226: Possible missing comma found.
Context: ...ite simpler (and more often performant) queries since there is no need to use `unless e...(AI_HYDRA_LEO_MISSING_COMMA)
agoode
force-pushed
the
nan
branch
2 times, most recently
from
e0a9945
to
41f75df
Compare
agoode
changed the title
export_unavailable_metrics
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (1)
source/_integrations/prometheus.markdown (1)
215-216: Remove extra blank line.To comply with Markdown best practices and improve consistency, please remove one of the blank lines after the note's closing tag.
{% endnote %} -🧰 Tools
🪛 Markdownlint
216-216: Expected: 1; Actual: 2
Multiple consecutive blank lines(MD012, no-multiple-blanks)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
- source/_integrations/prometheus.markdown (1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/prometheus.markdown
[style] ~201-~201: ‘Prior to’ might be wordy. Consider a shorter alternative.
Context: ...y when available and known. {% note %} Prior to Home Assistant 2024.10, this component ...(EN_WORDINESS_PREMIUM_PRIOR_TO)
[style] ~203-~203: Consider a shorter alternative to avoid wordiness.
Context: ...availablecorresponding metric to 0. In order to filter out these stale values,entity...(IN_ORDER_TO_PREMIUM)
🪛 Markdownlint
source/_integrations/prometheus.markdown
216-216: Expected: 1; Actual: 2
Multiple consecutive blank lines(MD012, no-multiple-blanks)
🔇 Additional comments (4)
source/_integrations/prometheus.markdown (4)
197-199: Clear explanation of the new behavior for unavailable or unknown entities.The documentation accurately describes how the Prometheus exporter handles entities in unavailable or unknown states. This change improves the clarity and consistency of the exported metrics.
201-204: Clear explanation of the behavior change in Home Assistant 2024.10.The note effectively communicates the important change in behavior for the Prometheus exporter. This information is crucial for users upgrading from earlier versions.
Minor style suggestion: Consider replacing "Prior to" with "Before" for slightly more concise wording, but this is not critical as the current phrasing is clear.
🧰 Tools
🪛 LanguageTool
[style] ~201-~201: ‘Prior to’ might be wordy. Consider a shorter alternative.
Context: ...y when available and known. {% note %} Prior to Home Assistant 2024.10, this component ...(EN_WORDINESS_PREMIUM_PRIOR_TO)
[style] ~203-~203: Consider a shorter alternative to avoid wordiness.
Context: ...availablecorresponding metric to 0. In order to filter out these stale values,entity...(IN_ORDER_TO_PREMIUM)
204-211: Clear explanation of the old filtering method with a helpful example.The documentation effectively explains the previous method of filtering out stale values using
entity_available, including a practical YAML example. This context is valuable for users transitioning from the old behavior.Minor suggestion: Consider replacing "In order to filter out" with "To filter out" for improved conciseness.
211-214: Clear explanation of the simplified querying andentity_availablebehavior.The documentation effectively communicates that the old filtering method is no longer necessary and that queries can now be simpler. The information about
entity_availablemetrics always being 1 is crucial for users to understand the new behavior.Minor correction needed: Add a comma after "simpler" in the following sentence:
-This is no longer necessary, since all such metrics are now unexported, making it possible to write simpler (and more often performant) queries. +This is no longer necessary, since all such metrics are now unexported, making it possible to write simpler, (and more often performant) queries.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (2)
source/_integrations/prometheus.markdown (2)
201-204: Clear explanation of previous behavior with version-specific information.This note effectively communicates the change in behavior, providing important context for users upgrading from older versions. The specific mention of Home Assistant 2024.10 is helpful for version tracking.
Consider a minor wording adjustment for improved clarity:
-Prior to Home Assistant 2024.10, this component would continue to export the latest known value when an entity would become unavailable or unknown and set the `entity_available` corresponding metric to 0. +Prior to Home Assistant 2024.10, this component would continue to export the latest known value when an entity became unavailable or unknown, and set the corresponding `entity_available` metric to 0.🧰 Tools
🪛 LanguageTool
[style] ~201-~201: ‘Prior to’ might be wordy. Consider a shorter alternative.
Context: ...y when available and known. {% note %} Prior to Home Assistant 2024.10, this component ...(EN_WORDINESS_PREMIUM_PRIOR_TO)
[style] ~203-~203: Consider a shorter alternative to avoid wordiness.
Context: ...availablecorresponding metric to 0. In order to filter out these stale values,entity...(IN_ORDER_TO_PREMIUM)
211-213: Clear explanation of benefits from the new approach.This segment effectively communicates that the previous workaround is no longer necessary and highlights the advantages of the new approach, including simpler and potentially more performant queries.
Consider a minor grammatical adjustment for improved clarity:
-This is no longer necessary, since all such metrics are now unexported, making it possible to write simpler (and more often performant) queries. +This is no longer necessary, since all such metrics are now unexported, making it possible to write simpler (and often more performant) queries.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
- source/_integrations/prometheus.markdown (1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/prometheus.markdown
[style] ~201-~201: ‘Prior to’ might be wordy. Consider a shorter alternative.
Context: ...y when available and known. {% note %} Prior to Home Assistant 2024.10, this component ...(EN_WORDINESS_PREMIUM_PRIOR_TO)
[style] ~203-~203: Consider a shorter alternative to avoid wordiness.
Context: ...availablecorresponding metric to 0. In order to filter out these stale values,entity...(IN_ORDER_TO_PREMIUM)
🔇 Additional comments (4)
source/_integrations/prometheus.markdown (4)
197-199: Excellent addition explaining the new behavior for unavailable or unknown entities.This new explanation clearly describes how the Prometheus exporter handles entities in unavailable or unknown states, both at startup and during runtime. This information is crucial for users to understand the changes in behavior and aligns well with the PR objectives.
204-210: Helpful explanation of previous workaround with clear example.This segment effectively explains the previous method for filtering out stale values using
entity_available. The inclusion of a YAML example for a recording rule is particularly useful for users who might have been employing this approach. This context helps users understand the rationale behind the changes and how it simplifies their Prometheus queries.
213-215: Important clarification onentity_availablemetrics.This concise statement clearly explains that all
entity_availablemetrics are now always set to 1. This information is crucial for maintaining compatibility with existing queries and helps users understand how to interpret these metrics in the new system.
197-215: Excellent documentation update for the new Prometheus integration behavior.This comprehensive update to the Prometheus integration documentation effectively communicates the new behavior regarding unavailable or unknown entities. The changes are well-structured, providing:
- Clear explanation of the new behavior
- Context about the previous behavior and its limitations
- Examples of how users might have worked around these limitations in the past
- Benefits of the new approach
- Important information for maintaining compatibility with existing setups
This level of detail and clarity will greatly assist users in understanding and adapting to the new behavior. Great job on providing such a thorough and user-friendly documentation update!
🧰 Tools
🪛 LanguageTool
[style] ~201-~201: ‘Prior to’ might be wordy. Consider a shorter alternative.
Context: ...y when available and known. {% note %} Prior to Home Assistant 2024.10, this component ...(EN_WORDINESS_PREMIUM_PRIOR_TO)
[style] ~203-~203: Consider a shorter alternative to avoid wordiness.
Context: ...availablecorresponding metric to 0. In order to filter out these stale values,entity...(IN_ORDER_TO_PREMIUM)
Proposed change
This documents the new prometheus behavior added in home-assistant/core#125492.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
New Features
export_unavailable_metrics, allowing users to control metric exports during entity unavailability. The default value will change fromtruetofalsein early 2025.Documentation
export_unavailable_metricsattribute, enhancing user understanding of its functionality.