ecs-logging-python provides logging formatters for Python's standard `logging` module and `structlog`, enabling applications to produce logs compliant with the Elastic Common Schema (ECS). It helps in standardizing log formats for easier ingestion and analysis in Elastic Stack products like Elasticsearch and Kibana. The library is currently at version 2.3.0 and is actively maintained, with a focus on adding new features and supporting recent Python versions.
pip install ecs-loggingVerified import paths — ran on the pinned version, not inferred.
This example demonstrates how to configure the standard Python `logging` module to output ECS-compliant JSON logs to `stdout`. It includes an example of adding custom fields via the `extra` dictionary and logging an exception.
Upgrade your Python environment to Python 3.6+ (v2.0.0 required >=3.6) or specifically >=3.8 for current versions.
Upgrade your Python environment to Python 3.6+.
Always use `logger.info('message', extra={'field.subfield': 'value'})` for custom ECS fields.Ensure `ecs_logging.StructlogFormatter()` is the final item in the `processors` list when configuring `structlog`.
If you need unescaped non-ASCII characters (e.g., for direct display in certain terminals or systems), initialize the formatter with `ensure_ascii=False`: `ecs_logging.StdlibFormatter(ensure_ascii=False)`.
Upgrade to version 1.0.2 or higher.
Ensure the library is installed using pip: `python -m pip install ecs-logging`
Pass `exclude_fields` as a list of strings, for example: `formatter = ecs_logging.StdlibFormatter(exclude_fields=['log.original', 'process'])`
Ensure that the data provided to your logger (especially in the `extra` dictionary) for specific ECS fields adheres to the expected data types defined by the Elastic Common Schema and your Elasticsearch index mappings. Validate input data before logging it to prevent type mismatches (e.g., ensure `client.ip` is a valid IP address or null/absent if unknown).