feat(connectors-sdk): add `logging` module and expose `Logger` (#6558) by Powlinett · Pull Request #6559 · OpenCTI-Platform/connectors

Powlinett · 2026-05-28T17:25:07Z

Proposed changes

add logging module:
- BaseLogger parses the connector's configured log level (default to "ERROR")
- BaseLogger uses the same handler and formatter as pycti
- BaseLogger is able to create child loggers
- SDKLogger inherits from BaseLogger and is responsible of internal logs
- Logger inherits from BaseLogger and is responsible of internal logs
use SDKLogger and Logger in other modules (replacing ConnectorLogger placeholder)
add and update unit tests

Related issues

close feat(connectors-sdk): add logging module #6558

Checklist

I consider the submitted work as finished
I have signed my commits using GPG key.
I tested the code for its functionality using different use cases
I added/update the relevant documentation (either on github or on notion)
Where necessary I refactored code to improve the overall quality

Further comments

The review can be done commit by commit. The most important ones are:

feat: create logging module
feat: replace OpenCTIConnectorHelper's logger by BaseLogger subclasses

⚠️ WorkManager class was exposed in the public API. I removed it. It's technically a breaking changes but no connectors are using it for now so it's still safe to remove 👍️

codecov · 2026-05-28T17:27:18Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #6559       +/-   ##
===========================================
+ Coverage   35.64%   69.02%   +33.37%     
===========================================
  Files        2048     1134      -914     
  Lines      125310    59742    -65568     
===========================================
- Hits        44672    41235     -3437     
+ Misses      80638    18507    -62131

Files with missing lines	Coverage Δ
connectors-sdk/connectors_sdk/__init__.py	`100.00% <100.00%> (ø)`
...rs_sdk/connectors/external_import/_work_manager.py	`100.00% <100.00%> (ø)`
.../connectors/external_import/base_data_processor.py	`100.00% <100.00%> (ø)`
...ctors/external_import/external_import_connector.py	`100.00% <100.00%> (ø)`
...nectors-sdk/connectors_sdk/logging/_base_logger.py	`100.00% <100.00%> (ø)`
connectors-sdk/connectors_sdk/logging/logger.py	`100.00% <100.00%> (ø)`
...onnectors-sdk/connectors_sdk/logging/sdk_logger.py	`100.00% <100.00%> (ø)`
...rs-sdk/connectors_sdk/settings/_settings_loader.py	`100.00% <100.00%> (ø)`
...ors-sdk/connectors_sdk/settings/annotated_types.py	`100.00% <ø> (ø)`
...ctors-sdk/connectors_sdk/settings/base_settings.py	`100.00% <100.00%> (ø)`
... and 1 more

... and 1110 files with indirect coverage changes

📢 Thoughts on this report? Let us know!

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull request overview

This PR introduces a new connectors_sdk.logging module (with BaseLogger, Logger, and SDKLogger) and refactors connectors-sdk internals/tests to use it instead of the previous ConnectorLogger placeholder, aiming to provide pycti-compatible JSON logs without depending on OpenCTIConnectorHelper for logging.

Changes:

Added a new logging subsystem (BaseLogger, Logger, SDKLogger) and exposed Logger/logger from the root SDK API.
Refactored connectors-sdk components (state, settings, external-import connector/work manager/data processor) to use the new loggers and class-level child loggers.
Reorganized settings loading by extracting _SettingsLoader into its own module and updated/added unit tests accordingly.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
connectors-sdk/tests/tests_states/test_base_state.py	Adds subclass-init logger assertions for state classes.
connectors-sdk/tests/test_settings/test_settings_loader.py	New test module covering `_SettingsLoader` path resolution and parsing behavior.
connectors-sdk/tests/test_settings/test_base_settings.py	Removes loader tests (moved) and adds logger subclass-init assertions; updates expected log level to debug.
connectors-sdk/tests/test_settings/conftest.py	Updates fixtures and test data paths; switches test log level to debug.
connectors-sdk/tests/test_logging/test_sdk_logger.py	Adds tests for `SDKLogger` behavior and module-level `sdk_logger`.
connectors-sdk/tests/test_logging/test_logger.py	Adds tests for connector-facing `Logger` and module-level `logger`.
connectors-sdk/tests/test_logging/test_base_logger.py	Adds comprehensive tests for `BaseLogger` (handlers, levels, meta mapping, child loggers).
connectors-sdk/tests/test_logging/conftest.py	Adds fixtures to fake config.yml/.env presence for log-level resolution tests.
connectors-sdk/tests/test_connectors/test_work_manager.py	Updates work manager tests to match new `_Work`/`WorkManager` signatures and SDK logging.
connectors-sdk/tests/test_connectors/test_logger.py	Removes tests for the deleted `ConnectorLogger`.
connectors-sdk/tests/test_connectors/test_external_import_connector.py	Updates connector tests to use `Logger` and datetime state fields.
connectors-sdk/tests/test_connectors/test_data_processor.py	Updates processor tests to use class logger and new dependency injection signature.
connectors-sdk/tests/test_connectors/conftest.py	Removes `ConnectorLogger` fixture no longer needed.
connectors-sdk/tests/test_api.py	Updates root API expectations (adds `Logger`/`logger`, removes `WorkManager`/`ConnectorLogger`).
connectors-sdk/tests/data/config.test.yml	Sets `connector.log_level` to `debug` for updated tests.
connectors-sdk/tests/data/.env.test	Sets `CONNECTOR_LOG_LEVEL` to `debug` for updated tests.
connectors-sdk/tests/conftest.py	Adds shared `mock_main_path` fixture for settings/logger path resolution.
connectors-sdk/TDRs/2026-04-14-Typing_and_validation_of_connector_state_with_pydantic.md	Updates logging usage in documentation examples.
connectors-sdk/pyproject.toml	Adds `python-dotenv` dependency used by new logger for `.env` lookups.
connectors-sdk/docs/Dummy_end_to_end_test_octi_models_example.md	Updates documentation example to use `connectors_sdk.logger`.
connectors-sdk/connectors_sdk/states/_base_state.py	Introduces SDK/connector loggers, adds debug logs, and centralizes JSON state serialization via `to_json()`.
connectors-sdk/connectors_sdk/settings/base_settings.py	Extracts `_SettingsLoader`, adds class loggers and debug logs around settings loading/instantiation.
connectors-sdk/connectors_sdk/settings/_settings_loader.py	New module encapsulating settings source resolution and raw-loader generation.
connectors-sdk/connectors_sdk/logging/sdk_logger.py	Adds `SDKLogger` and module-level singleton `sdk_logger`.
connectors-sdk/connectors_sdk/logging/logger.py	Adds connector-facing `Logger` and module-level singleton `logger`.
connectors-sdk/connectors_sdk/logging/_base_logger.py	Adds `BaseLogger` implementation (handlers/formatter, log-level discovery, meta mapping, child loggers).
connectors-sdk/connectors_sdk/logging/init.py	Introduces logging package marker.
connectors-sdk/connectors_sdk/connectors/external_import/logger.py	Deletes old `ConnectorLogger` wrapper.
connectors-sdk/connectors_sdk/connectors/external_import/external_import_connector.py	Switches to new logger, adds richer run/state lifecycle logs, and removes helper-backed logger wiring.
connectors-sdk/connectors_sdk/connectors/external_import/base_data_processor.py	Switches to class-level logger and removes helper-backed logger injection.
connectors-sdk/connectors_sdk/connectors/external_import/_work_manager.py	Switches to SDK logger, removes helper-backed logger plumbing, expands structured logging around work lifecycle.
connectors-sdk/connectors_sdk/connectors/external_import/init.py	Updates module docstring to reference `Logger`.
connectors-sdk/connectors_sdk/init.py	Exposes `Logger`/`logger` in public API and removes `WorkManager`/`ConnectorLogger` exports.

+    @classmethod
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Setup default logging settings:
+        - add a default `StreamHandler` to stderr with pycti's JSON formatter.
+        - set log level according to the connector's configuration.
+        This method ensures that all subclasses share the same default handlers and log level.
+        """
+        super().__init_subclass__(**kwargs)
+
+        stderr_handler = logging.StreamHandler()
+        stderr_handler.set_name("default_stderr_handler")
+        stderr_handler.setFormatter(_json_formatter())  # pycti's formatter
+        cls._handlers = [stderr_handler]
+
+        connector_log_level = cls._get_connector_log_level()
+        if connector_log_level:
+            cls._log_level = connector_log_level
+


+            message: The log message.
+            meta: Optional metadata dict.
+        """
+        self._logger.error(message, exc_info=True, extra=_prepare_meta(meta))


comment #6559 (comment)