{"id":2492,"library":"ecs-logging","title":"ECS Logging for Python","description":"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.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/elastic/ecs-logging-python","tags":["logging","ecs","elastic","structured-logging","observability"],"install":[{"cmd":"pip install ecs-logging","lang":"bash","label":"Install ecs-logging"}],"dependencies":[{"reason":"Optional dependency for automatic collection of ECS tracing fields to correlate logs with spans, transactions, and traces in Elastic APM.","package":"elastic-apm","optional":true},{"reason":"Required if using the `ecs_logging.StructlogFormatter` for structured logging with `structlog`.","package":"structlog","optional":true}],"imports":[{"symbol":"StdlibFormatter","correct":"from ecs_logging import StdlibFormatter"},{"note":"The `StructlogFormatter` is directly available under the `ecs_logging` top-level package since version 1.0.0.","wrong":"from ecs_logging.structlog import StructlogFormatter","symbol":"StructlogFormatter","correct":"from ecs_logging import StructlogFormatter"}],"quickstart":{"code":"import logging\nimport ecs_logging\nimport sys\n\n# Get the Logger\nlogger = logging.getLogger('app')\nlogger.setLevel(logging.DEBUG)\n\n# Add an ECS formatter to the Handler\nhandler = logging.StreamHandler(sys.stdout)\nhandler.setFormatter(ecs_logging.StdlibFormatter())\nlogger.addHandler(handler)\n\n# Emit a log!\nlogger.debug('Example message!', extra={'http.request.method': 'get', 'user.name': 'john.doe'})\n\ntry:\n    1 / 0\nexcept ZeroDivisionError:\n    logger.error('An error occurred!', exc_info=True)\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to Python 3.6+ (v2.0.0 required >=3.6) or specifically >=3.8 for current versions.","message":"Python 2 support was removed in version 2.0.0. Ensure your projects are running on Python 3.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Python environment to Python 3.6+.","message":"Python 3.5 support was removed in version 1.1.0.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Always use `logger.info('message', extra={'field.subfield': 'value'})` for custom ECS fields.","message":"When using `StdlibFormatter`, additional ECS fields must be passed via the `extra` dictionary argument to logging calls. Keys with dot notation (e.g., `user.name`) will automatically be de-dotted and nested in the output JSON.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `ecs_logging.StructlogFormatter()` is the final item in the `processors` list when configuring `structlog`.","message":"If using `structlog`, the `ecs_logging.StructlogFormatter` must be the *last* processor in your `structlog.configure` processor list, as it handles the final JSON conversion and ECS field enrichment.","severity":"gotcha","affected_versions":"All versions"},{"fix":"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)`.","message":"The `ensure_ascii` parameter for `StdlibFormatter` and `StructlogFormatter` (introduced in v2.3.0) controls whether non-ASCII characters in log messages are escaped to `\\uXXXX` sequences. It defaults to `True`.","severity":"gotcha","affected_versions":">=2.3.0"},{"fix":"Upgrade to version 1.0.2 or higher.","message":"Prior to v1.0.2, `StdlibFormatter` had a signature mismatch with `logging.Formatter` that could cause issues in frameworks like Django and Gunicorn.","severity":"gotcha","affected_versions":"<1.0.2"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}