Skip to content

Add page about logging in an integration #3042

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
joostlek wants to merge 4 commits into
base: master
Choose a base branch
from
+36 −0
Draft

Add page about logging in an integration #3042

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c3c9fda
Add page about logging in an integration
joostlek Apr 8, 2026
bebe1b4
Add page about logging in an integration
joostlek Apr 8, 2026
9ba0a1b
Add page about logging in an integration
joostlek Apr 8, 2026
f6f4202
Add page about logging in an integration
joostlek Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions docs/core/integration/logging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
title: "Logging"
---
A good way to find out what is going on in an integration is to have it log what it is doing.

:::warning
Please make sure not to spam the logs, as that will make it harder to find the relevant information and may cause performance issues.
:::

## Debug logging
Copy link
Copy Markdown
Member

@abmantis abmantis Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest rewording this section to be about "dependency logging", since it is not about debug logs only.
If the user has set the default logging to error and then sets it to info for the integration, this will also log info logs for the things listed in loggers, right?

Copy link
Copy Markdown
Member Author

@joostlek joostlek Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well it's not only about dependencies, because it's about how logging is enabled for both the integration module and the dependency.

You can't set the logging for an integration to info, if you do that via the logging module, I believe it literally only does that for that module, so it's not looking at "oh you log homeassistant.components.smartthings, let me also set pysmartthings to the same level"


By default, Home Assistant does not log debug messages.
Copy link
Copy Markdown
Member

@abmantis abmantis Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe reword this to something like "In order to enable additional modules logged when the user enables logs for an integration, set the modules i the loggers key of the manifest".
that way we make it clearer what we are discussing here, and focused on development and not how the user enables them.

Copy link
Copy Markdown
Member Author

@joostlek joostlek Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I started this paragraph more explaining what debug logs are and how they can help the developer with diagnosing issues. That was my goal at least. So more of a, this is debug logging, a non-intrusive way of fetching a stream of information on demand, and this is how the user enables it and what shouldn't be logged.

Not saying that your suggestion is bad, more trying to explain my thought process behind it

Debug logging can be enabled for the integration by the user as described in the [user documentation].
Enabling debug logging will set the log level for the integration module and for the module declared in the manifest to debug.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use plural "modules" for accuracy.

The phrase "the module declared in the manifest" implies a single module, but the loggers field is an array that can contain multiple module names. Use plural form for accuracy.

📝 Suggested fix 
-Enabling debug logging will set the log level for the integration module and for the module declared in the manifest to debug.
+Enabling debug logging will set the log level for the integration module and for the modules listed in the manifest's `loggers` field to debug.
📝 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.

Suggested change
Enabling debug logging will set the log level for the integration module and for the module declared in the manifest to debug.
Enabling debug logging will set the log level for the integration module and for the modules listed in the manifest's `loggers` field to debug.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/core/integration/logging.md` at line 14, Update the sentence to use
plural "modules": change "Enabling debug logging will set the log level for the
integration module and for the module declared in the manifest to debug." to
refer to "the integration module and the modules declared in the manifest" (or
similar plural phrasing) so it accurately reflects that the manifest's loggers
field can contain multiple module names.


So when debug logging is enabled for the following integration, it will set the log level to debug for both the `my_integration` and `dependency` modules:
```json
{
"domain": "my_integration",
"name": "My Integration",
"loggers": ["dependency"],
"requirements": ["dependency==0.2.1"]
}
```

:::warning
Make sure to not log sensitive information, as debug logs may be shared with others when troubleshooting issues.
:::

To enable debug logs for a specific module, users can either add `logger` configuration as described in [the logger documentation].
Or they can use the [`logger.set_level`] service to set the log level for the module to debug.

[user documentation]: https://www.home-assistant.io/docs/configuration/troubleshooting/#enabling-debug-logging
[`logger.set_level`]: https://www.home-assistant.io/integrations/logger/#action-set-level
[the logger documentation]: https://www.home-assistant.io/integrations/logger/
1 change: 1 addition & 0 deletions sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,7 @@ module.exports = {
label: "Debugging an integration",
items: [
"core/integration/diagnostics",
"core/integration/logging",
"core/integration/system_health",
],
},
Expand Down