Add opt-in per-instrument logger scope (default_logger_scope)

[ymampaey]

Closes #8522

Summary

Every instrument currently shares one logging.Logger object, because InstrumentBase.__init__ names it with a module constant:

self.log: InstrumentLoggerAdapter = get_instrument_logger(self, __name__)  # "qcodes.instrument.instrument_base"

Since logging.getLogger() caches by name, setLevel, addHandler and propagate set on one instrument apply to all of them. VisaInstrument.visa_log has the same problem via the constant VISA_LOGGER.

This PR lets a driver opt in to its own logger by setting one class attribute. QCoDeS only chooses the logger name — it still never sets levels, adds handlers or touches propagate; that stays driver/application policy.

MyDriver.default_logger_scope = "instrument"

The default is unchanged. Without opting in, logger names, records, formatting and filtering are byte-for-byte identical to today.

What the scoped names look like

The name is built from the driver class of the root_instrument followed by the instrument's name_parts, and stays a descendant of the existing shared logger:

qcodes.instrument.instrument_base                            <- shared logger (unchanged default)
qcodes.instrument.instrument_base.MyDriver                   <- the driver class
qcodes.instrument.instrument_base.MyDriver.myinst            <- one instrument
qcodes.instrument.instrument_base.MyDriver.myinst.ChanA      <- one of its channels

Each node is a real ancestor of the next, so a level set at any level is inherited by everything below it, and a level configured on qcodes.instrument.instrument_base (e.g. via logger_levels in qcodesrc.json) is still inherited by everything.

Examples

Per instrument

class ScopedAMIModel430(AMIModel430):
    default_logger_scope = "instrument"

mag_w = ScopedAMIModel430("w", address="GPIB::4::INSTR", ...)

mag_w.log.logger.setLevel(logging.DEBUG)   # only this magnet

Per driver class

This is the common driver-development case: a station often holds several instruments of the same driver (QCoDeS' own AMI430_3D test fixture builds mag_x, mag_y and mag_z, all AMIModel430) and you want DEBUG for all of them without listing their names.

logging.getLogger("qcodes.instrument.instrument_base.ScopedAMIModel430").setLevel(logging.DEBUG)

Because a level can be set on a logger before it exists, this also covers instruments created later and can be written declaratively in qcodesrc.json:

"logger_levels": {"qcodes.instrument.instrument_base.AMIModel430": "DEBUG"}

Submodules follow their instrument

inst.log.logger.setLevel(logging.DEBUG)
inst.submodules["A"].log.logger.getEffectiveLevel()   # DEBUG

Design notes

Why name_parts rather than full_name. name_parts is QCoDeS' canonical identity for an instrument. Joining the parts with . rather than using the _-joined full_name is what makes a channel logger a genuine child of its instrument's logger.

Why the class comes from root_instrument, not type(self). Using type(self) would put an instrument and its own channel in different subtrees (....MyDriver.myinst next to ....DummyChannel.myinst_ChanA), so inst.log.logger.setLevel(DEBUG) would silently not reach the instrument's channels. Taking the class from the root instrument keeps the whole tree under one class node.

Why the name extends the existing base instead of replacing it. A name derived from type(self).__module__ would put third-party drivers — and drivers defined in a notebook (__main__) — outside the qcodes.* tree, where logger_levels and dictConfig rules scoped to qcodes no longer apply. Keeping base also preserves the separation between log and visa_log, which are created from different base names.

default_logger_scope is a plain class attribute, not a ClassVar, matching the existing VisaInstrument.default_terminator / default_timeout precedent.

Known caveat (documented)

Python's logging registry keeps a strong reference to every logger and has no removal API, so under "instrument" scope repeatedly creating instruments with distinct names leaks one registry entry per name. Negligible for normal sessions; noted in the docs.

Changes

File	Change
src/qcodes/instrument/instrument_base.py	LoggerScope, default_logger_scope, _logger_name(), scoped self.log
src/qcodes/instrument/visa.py, ip_to_visa.py	scoped self.visa_log
tests/test_logger.py	16 new tests
docs/examples/logging/logging_example.ipynb	new "One logger per instrument" section
docs/changes/newsfragments/	newsfragment

Tests

New tests cover: default scope unchanged (regression guard); distinct loggers per instance; setLevel isolation; inheritance from the shared logger; class-level DEBUG reaching instruments created afterwards and their submodules but not other drivers; per-instrument level overriding the class level; submodule logger being a child of its instrument; filter_instrument still working under scoping; and the visa_log equivalents.

Full suite passes (3249 passed, 270 skipped; the one failure in test_installation_info is a pre-existing local environment issue unrelated to this change and reproduces on unmodified main). pyright reports 0 errors and pre-commit run --all passes. The updated notebook was executed end to end.

[microsoft-github-policy-service]

ymampaey please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

Contribution License Agreement

This Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
and conveys certain license rights to Microsoft Corporation and its affiliates (“Microsoft”) for Your
contributions to Microsoft open source projects. This Agreement is effective as of the latest signature
date below.

1. Definitions.
   “Code” means the computer software code, whether in human-readable or machine-executable form,
   that is delivered by You to Microsoft under this Agreement.
   “Project” means any of the projects owned or managed by Microsoft and offered under a license
   approved by the Open Source Initiative (www.opensource.org).
   “Submit” is the act of uploading, submitting, transmitting, or distributing code or other content to any
   Project, including but not limited to communication on electronic mailing lists, source code control
   systems, and issue tracking systems that are managed by, or on behalf of, the Project for the purpose of
   discussing and improving that Project, but excluding communication that is conspicuously marked or
   otherwise designated in writing by You as “Not a Submission.”
   “Submission” means the Code and any other copyrightable material Submitted by You, including any
   associated comments and documentation.
2. Your Submission. You must agree to the terms of this Agreement before making a Submission to any
   Project. This Agreement covers any and all Submissions that You, now or in the future (except as
   described in Section 4 below), Submit to any Project.
3. Originality of Work. You represent that each of Your Submissions is entirely Your original work.
   Should You wish to Submit materials that are not Your original work, You may Submit them separately
   to the Project if You (a) retain all copyright and license information that was in the materials as You
   received them, (b) in the description accompanying Your Submission, include the phrase “Submission
   containing materials of a third party:” followed by the names of the third party and any licenses or other
   restrictions of which You are aware, and (c) follow any other instructions in the Project’s written
   guidelines concerning Submissions.
4. Your Employer. References to “employer” in this Agreement include Your employer or anyone else
   for whom You are acting in making Your Submission, e.g. as a contractor, vendor, or agent. If Your
   Submission is made in the course of Your work for an employer or Your employer has intellectual
   property rights in Your Submission by contract or applicable law, You must secure permission from Your
   employer to make the Submission before signing this Agreement. In that case, the term “You” in this
   Agreement will refer to You and the employer collectively. If You change employers in the future and
   desire to Submit additional Submissions for the new employer, then You agree to sign a new Agreement
   and secure permission from the new employer before Submitting those Submissions.
5. Licenses.

• Copyright License. You grant Microsoft, and those who receive the Submission directly or
  indirectly from Microsoft, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license in the
  Submission to reproduce, prepare derivative works of, publicly display, publicly perform, and distribute
  the Submission and such derivative works, and to sublicense any or all of the foregoing rights to third
  parties.
• Patent License. You grant Microsoft, and those who receive the Submission directly or
  indirectly from Microsoft, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license under
  Your patent claims that are necessarily infringed by the Submission or the combination of the
  Submission with the Project to which it was Submitted to make, have made, use, offer to sell, sell and
  import or otherwise dispose of the Submission alone or with the Project.
• Other Rights Reserved. Each party reserves all rights not expressly granted in this Agreement.
  No additional licenses or rights whatsoever (including, without limitation, any implied licenses) are
  granted by implication, exhaustion, estoppel or otherwise.

6. Representations and Warranties. You represent that You are legally entitled to grant the above
   licenses. You represent that each of Your Submissions is entirely Your original work (except as You may
   have disclosed under Section 3). You represent that You have secured permission from Your employer to
   make the Submission in cases where Your Submission is made in the course of Your work for Your
   employer or Your employer has intellectual property rights in Your Submission by contract or applicable
   law. If You are signing this Agreement on behalf of Your employer, You represent and warrant that You
   have the necessary authority to bind the listed employer to the obligations contained in this Agreement.
   You are not expected to provide support for Your Submission, unless You choose to do so. UNLESS
   REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING, AND EXCEPT FOR THE WARRANTIES
   EXPRESSLY STATED IN SECTIONS 3, 4, AND 6, THE SUBMISSION PROVIDED UNDER THIS AGREEMENT IS
   PROVIDED WITHOUT WARRANTY OF ANY KIND, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY OF
   NONINFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
7. Notice to Microsoft. You agree to notify Microsoft in writing of any facts or circumstances of which
   You later become aware that would make Your representations in this Agreement inaccurate in any
   respect.
8. Information about Submissions. You agree that contributions to Projects and information about
   contributions may be maintained indefinitely and disclosed publicly, including Your name and other
   information that You submit with Your Submission.
9. Governing Law/Jurisdiction. This Agreement is governed by the laws of the State of Washington, and
   the parties consent to exclusive jurisdiction and venue in the federal courts sitting in King County,
   Washington, unless no federal subject matter jurisdiction exists, in which case the parties consent to
   exclusive jurisdiction and venue in the Superior Court of King County, Washington. The parties waive all
   defenses of lack of personal jurisdiction and forum non-conveniens.
10. Entire Agreement/Assignment. This Agreement is the entire agreement between the parties, and
    supersedes any and all prior agreements, understandings or communications, written or oral, between
    the parties relating to the subject matter hereof. This Agreement may be assigned by Microsoft.

[Copilot]

Copilot review overview

🟡 Changes recommended

Logger identity collisions and mutable scope resolution can break the promised isolation and hierarchy.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 2 · 2

Open (5)

• Use module-qualified identities for per-driver logger isolation · New
• Store scope at root initialization for all descendants · New
• Avoid ambient logging levels in class logger test · New
• Clarify propagate=False and separate VISA logger behavior · New
• Document permanent logging-registry growth caveat · New

What changed in this PR

Adds opt-in per-instrument logger hierarchies while preserving shared logging by default.

Changes:

• Adds configurable logger scope and hierarchical names.
• Applies scoped naming to VISA loggers.
• Adds tests, documentation, and a newsfragment.

File	Description
instrument_base.py	Defines logger scopes and scoped-name generation.
visa.py	Applies scoped VISA logging.
ip_to_visa.py	Applies scoped logging to simulated VISA instruments.
test_logger.py	Tests scope, inheritance, filtering, and VISA behavior.
logging_example.ipynb	Documents scoped logger usage.
8523.new	Announces the feature.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Jens Hedegaard Nielsen (jenshnielsen)]

This would basically be equivalent to replacing base which is currently the name of this module qcodes.instrument.instrument_base with the name of the module that the instrument is defined in. qcodes.insrument.instrument_vendor.instrument_filename. I think I agreee that I would prefer this

[ymampaey]

One blocker for replacing base with the name of the module the instrument is defined in: _logger_name is called with two different bases, name for self.log and VISA_LOGGER for self.visa_log. Drop base, and those two become the same logger name, so driver messages and wire traffic can no longer be separated at all. Module-only also wouldn't distinguish AMIModel430 from AMIModel4303D, since both live in AMI430_visa.py.

The problem is:

vendor_a.Model372  ->  qcodes.instrument.instrument_base.Model372   ┐ same
vendor_b.Model372  ->  qcodes.instrument.instrument_base.Model372   ┘ logger

Not sure if vendors will realistically have the same module number, but perhaps these other sources could cause a problem:

• Same driver, two sources: a driver in qcodes.instrument_drivers.X and a fork/variant in qcodes_contrib_drivers or a local copy. Same class name by construction, since one is derived from the other.
• Notebook drivers: a user's quick class MyDriver(VisaInstrument) in main, which collides with anyone else's MyDriver.
• Subclassing in place: class AMIModel430(AMIModel430) style local tweaks.

In the category "same lineage, different module". Copilot's finding is technically correct but low severity: it needs a self-inflicted name clash, and the consequence is a shared log level, not data loss or a crash.

We could do the following:

     def _logger_name(self, base: str) -> str:
         root = self.root_instrument
         if root.default_logger_scope == "instrument":
-            return ".".join((base, type(root).__name__, *self.name_parts))
+            return ".".join((base, full_class(root), *self.name_parts))
         return base

So it would look like:

qcodes.instrument.instrument_base.qcodes.instrument_drivers.american_magnetics.AMI430_visa.AMIModel430.inst
qcodes.instrument.instrument_base.qcodes.instrument_drivers.tektronix.AWG5208.TektronixAWG5208.inst
                                  └──────────────── full_class ────────────────┘

Which is safer but very verbose. Another alternative is leaving it as is and documenting the behavior.

[Copilot]

One or more custom setup steps configured for this repository failed during this Copilot code review run:

Fetch main branch

Setup steps run before each review. If the review above is missing context, or no review was posted at all, the failing step above may be the cause. See the workflow run for failure details, fix your setup steps configuration, and re-request a review.

Note

You can configure setup steps for Copilot code review separately from Copilot cloud agent with a copilot-code-review.yml file. Read the docs for details.

[codecov]

Codecov Report

❌ Patch coverage is 93.33333% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 72.21%. Comparing base (f6b9dd6) to head (ea454fa).
⚠️ Report is 119 commits behind head on main.

Files with missing lines	Patch %	Lines
src/qcodes/instrument/ip_to_visa.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8523      +/-   ##
==========================================
+ Coverage   72.00%   72.21%   +0.21%     
==========================================
  Files         305      307       +2     
  Lines       32019    32333     +314     
==========================================
+ Hits        23055    23350     +295     
- Misses       8964     8983      +19     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.