[datadog_checks_base] Add include_total option for Windows perf-counter framework

[ollie-har]

What does this PR do?

Adds a per-performance-object include_total: bool option (default false) to the Windows perf-counter framework in datadog_checks_base.

When set to true, the framework no longer hardcodes \b_Total\b into the exclude pattern, so the _Total aggregate instance is collected like any other instance. Default behaviour is unchanged.

Motivation

Reported via AGENT-16101. A customer is migrating an integration from the legacy PDH-based framework (where they could collect _Total) to the current PdhCounterSet framework (where _Total is unconditionally excluded). They rely on _Total aggregates for capacity dashboards and have no in-Agent way to opt back into them.

The current behaviour was introduced as a sensible default to prevent double-counting, and that default should stay. But there are legitimate cases where the aggregate is the metric the user wants, so an opt-in escape hatch is reasonable.

This is conceptually adjacent to #22028 which let users opt out of the default exclude behaviour for namespaced instances — include_total extends the same idea to the _Total row specifically.

Describe how you validated your changes

• py_compile clean on counter.py and test_filter.py.
• 12-case standalone harness exercising the regex-compilation and _instance_excluded logic — all pass. Cases include:
  • default path (_Total still excluded, behaviour unchanged)
  • new opt-in path with include_total: true (_Total kept, other defaults still applied)
  • the customer's include: [_total] config (still dropped without opt-in, kept with opt-in)
  • (?!) never-match sentinel edge case (so exclude_pattern.search() callers don't have to handle None)
• Added 3 framework tests: test_include_total, test_include_total_with_lowercase_instance, test_include_total_respects_user_exclude. These are gated requires_windows, so they skip locally on darwin and run on the Windows CI runner.

Possible Drawbacks / Trade-offs

• Config surface grows by one option per perf-object. Kept defaults conservative so existing integrations are unaffected.
• Users opting in are responsible for not double-counting _Total alongside summed per-instance metrics.

Additional Notes

Draft - opening for review while a customer-built wheel is shared with the reporter for validation against their environment.

[datadog-datadog-prod-us1-2]

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 87.67% (+0.54%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: be53280 | Docs | Datadog PR Page | Give us feedback!}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.79%. Comparing base (94d61dd) to head (be53280).

Additional details and impacted files

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dd-octo-sts]

Validation Report

Validation	Description	Status
config	Validate default configuration files against spec.yaml	❌
models	Validate configuration data models match spec.yaml	❌

Run ddev validate all changed --fix to attempt to auto-fix supported validations.

Passed validations (18)

Validation	Description	Status
agent-reqs	Verify check versions match the Agent requirements file	✅
ci	Validate CI configuration and Codecov settings	✅
codeowners	Validate every integration has a CODEOWNERS entry	✅
dep	Verify dependency pins are consistent and Agent-compatible	✅
http	Validate integrations use the HTTP wrapper correctly	✅
imports	Validate check imports do not use deprecated modules	✅
integration-style	Validate check code style conventions	✅
jmx-metrics	Validate JMX metrics definition files and config	✅
labeler	Validate PR labeler config matches integration directories	✅
legacy-signature	Validate no integration uses the legacy Agent check signature	✅
license-headers	Validate Python files have proper license headers	✅
licenses	Validate third-party license attribution list	✅
metadata	Validate metadata.csv metric definitions	✅
openmetrics	Validate OpenMetrics integrations disable the metric limit	✅
package	Validate Python package metadata and naming	✅
readmes	Validate README files have required sections	✅
saved-views	Validate saved view JSON file structure and fields	✅
version	Validate version consistency between package and changelog	✅

View full run