{"id":50550736,"url":"https://github.com/uktrade/django-log-formatter-asim","last_synced_at":"2026-06-04T03:01:45.139Z","repository":{"id":336467515,"uuid":"719186320","full_name":"uktrade/django-log-formatter-asim","owner":"uktrade","description":"Django log formatter that uses ASIM format","archived":false,"fork":false,"pushed_at":"2026-02-04T16:36:36.000Z","size":297,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-02-05T01:50:15.810Z","etag":null,"topics":["django","logging","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uktrade.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY_CHECKLST.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-11-15T16:28:01.000Z","updated_at":"2026-02-04T16:37:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/uktrade/django-log-formatter-asim","commit_stats":null,"previous_names":["uktrade/django-log-formatter-asim"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/uktrade/django-log-formatter-asim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uktrade%2Fdjango-log-formatter-asim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uktrade%2Fdjango-log-formatter-asim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uktrade%2Fdjango-log-formatter-asim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uktrade%2Fdjango-log-formatter-asim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uktrade","download_url":"https://codeload.github.com/uktrade/django-log-formatter-asim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uktrade%2Fdjango-log-formatter-asim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33887124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","logging","python"],"created_at":"2026-06-04T03:01:44.358Z","updated_at":"2026-06-04T03:01:45.126Z","avatar_url":"https://github.com/uktrade.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django ASIM log formatter\n\nThe library formats Django logs in [ASIM format](https://learn.microsoft.com/en-us/azure/sentinel/normalization).\n\nMapping to the format may not be complete, but best effort has been made to create logical field mappings.\n\n## Installation\n\n``` shell\npip install django-log-formatter-asim\n```\n\n## Usage\n\nThis package provides the following ASIM functionality:\n\n- A Python [logging.Formatter] implementation.\n- A module of functions `django_log_formatter_asim.events` which generate ASIM event log entries.\n\n[logging.Formatter]: https://docs.python.org/3/library/logging.html#formatter-objects\n\n### `logging.Formatter` setup\n\nUsing the formatter in a Django logging configuration:\n\n``` python\nfrom django_log_formatter_asim import ASIMFormatter\n\nLOGGING = {\n    ...\n    \"formatters\": {\n        \"asim_formatter\": {\n            \"()\": ASIMFormatter,\n        },\n    },\n    'handlers': {\n        'asim': {\n            'formatter': 'asim_formatter',\n            ...\n        },\n    },\n    \"root\": {\n        \"handlers\": [\"asim\"],\n        ...\n    }\n    \"loggers\": {\n        \"django\": {\n            \"handlers\": [\"asim\"],\n            \"propagate\": False\n            ...\n        },\n    },\n}\n```\n\nIn this example we assign the ASIM formatter to a `handler` and ensure both `root` and `django` loggers use this `handler`.\nWe then set `propagate` to `False` on the `django` logger, to avoid duplicating logs at the root level.\n\n### Settings\n\n`DLFA_LOG_PERSONALLY_IDENTIFIABLE_INFORMATION` - the formatter checks this setting to see if personally identifiable information should be logged. If this is not set to true, only the user's id is logged.\n\n`DLFA_TRACE_HEADERS` - used for defining custom zipkin headers, the defaults is `(\"X-Amzn-Trace-Id\")`, but for applications hosted in GOV.UK PaaS you should use `(\"X-B3-TraceId\", \"X-B3-SpanId\")`. If you are running your application in both places side by side during migration, the following should work in your Django settings:\n\n```python\nfrom dbt_copilot_python.utility import is_copilot\n\nif is_copilot():\n   DLFA_TRACE_HEADERS = (\"X-B3-TraceId\", \"X-B3-SpanId\")\n```\n\n`DLFA_INCLUDE_RAW_LOG` - By default the original unformatted log is not included in the ASIM formatted log. You can enable that by setting this to `True` and it will be included in `AddidtionalFields.RawLog`.\n\n\u003e [!WARNING]\n\u003e Setting `DLFA_INCLUDE_RAW_LOG` to `True` will cause additional private fields to be output to your logs.\n\u003e This could include secrets, such as AWS Access Keys, private HTTP Request data, or personally identifiable information.\n\u003e This setting is not recommended for a production environment.\n\n### Serialisation behaviour\n\nThe package provides one `logging.Formatter` class, `ASIMFormatter` which routes log messages to a serialiser\nwhich generates a python dict which the formatter converts to a JSON string and prints to standard output.\n\nIt has a generic serialiser called `ASIMRootFormatter` and a custom serlializer for log messages where the\nlogger is `django.request`.\n\n``` python\n    ASIM_FORMATTERS = {\n        \"root\": ASIMRootFormatter,\n        \"django.request\": ASIMRequestFormatter,\n    }\n```\n\n#### ASIMRootFormatter\n\nThis serialiser outputs the following ASIM fields.\n\n- `EventSchema` = `ProcessEvent`\n- `ActingAppType` = `Django`\n- `AdditionalFields[DjangoLogFormatterAsimVersion]`\n- `EventSchemaVersion`\n- `EventMessage`\n- `EventCount`\n- `EventStartTime`\n- `EventEndTime`\n- `EventType`\n- `EventResult`\n- `EventSeverity`\n- `EventOriginalSeverity`\n\nAdditionally, the following DataDog fields where available:\n\n- `dd.trace_id`\n- `dd.span_id`\n- `env`\n- `service`\n- `version`\n\n\n#### ASIMRequestFormatter\n\nThis serialiser outputs the following ASIM fields in addition to the ones from ASIMRootFormatter.\nIt is coupled to the datastructure provided by the `django.request` logger.\nThe `django.request` logger only outputs requests where the response code is 4xx/5xx.\n\n- `SrcIpAddr` and `IpAddr`\n- `SrcPortNumber`\n- `SrcUserId` and `SrcUsername`\n- `HttpUserAgent`\n- `AdditionalFields[\"TraceHeaders\"][trace_header_name]` - See `DLFA_TRACE_HEADERS` setting for more information.\n\n#### Creating a custom serialiser\n\nIf you wish to create your own ASIM serialiser, you can inherit from `ASIMRootFormatter` and call\n`super().get_log_dict()` to get the base level logging data for augmentation:\n\n``` python\n    class MyASIMFormatter(ASIMRootFormatter):\n        def get_log_dict(self):\n            log_dict = super().get_log_dict()\n\n            # Customise logger event\n\n            return log_dict\n```\n\nThis serialiser can then be added to `ASIM_FORMATTERS`...\n\n```python\nASIM_FORMATTERS[\"my_logger\"] = MyASIMFormatter\n```\n\n\n### ASIM Events\n\nThe events mostly follow the Microsoft schema but have been tailored to Department of Business and Trade needs.\n\nEvents are designed for simple integrate into your Django app.\nEach will take additional information from the [Django HttpRequest object][django-request].\n\n[django-request]: https://docs.djangoproject.com/en/5.2/ref/request-response/#httprequest-objects\n\n#### Authentication event\n\nFollowing the [ASIM Authentication Schema](https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-authentication).\n\n```python\n# Example usage\nfrom django_log_formatter_asim.events import log_authentication\n\nlog_authentication(\n    request,\n    event=log_authentication.Event.Logoff,\n    result=log_authentication.Result.Success,\n    login_method=log_authentication.LoginMethod.UsernamePassword,\n)\n\n# Example JSON printed to standard output\n{\n    # Values provided as arguments\n    \"EventType\": \"Logoff\",\n    \"EventResult\": \"Success\",\n    \"LogonMethod\": \"Username \u0026 Password\",\n\n    # Calculated / Hard coded fields\n    \"EventStartTime\": \"2025-07-02T08:15:20+00:00\",\n    \"EventSeverity\": \"Informational\",\n    \"EventOriginalType\": \"001c\",\n    \"EventSchema\": \"Authentication\",\n    \"EventSchemaVersion\": \"0.1.4\",\n\n    # Taken from Django HttpRequest object\n    \"HttpHost\": \"WebServer.local\",\n    \"SrcIpAddr\": \"192.168.1.101\",\n    \"TargetUrl\": \"https://WebServer.local/steel\",\n    \"TargetSessionId\": \"def456\",\n    \"TargetUsername\": \"Adrian\"\n\n    # Taken from DBT Platform environment variables\n    \"TargetAppName\": \"export-analytics-frontend\",\n}\n```\n\n#### File Activity event\n\nFollowing the [ASIM File Event Schema](https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-file-event).\n\n```python\n# Example usage\nfrom django_log_formatter_asim.events import log_file_activity\n\nlog_file_activity(\n    request,\n    event=log_file_activity.Event.FileCopied,\n    result=log_file_activity.Result.Success,\n    file={\n        \"path\": \"/tmp/copied.txt\",\n        \"content_type\": \"text/plain\",\n        \"extension\": \"txt\",\n        \"name\": \"copied.txt\",\n        \"sha256\": \"6798b7a132f37a0474002dec538ec52bdcd5f7b76e49e52c8a3d2016ca8d1d18\",\n        \"size\": 14,\n    },\n    # source_file is only necessary if the event is one of FileRenamed, FileMoved, FileCopied, FolderMoved\n    source_file={\n        \"path\": \"/tmp/original.txt\",\n        \"content_type\": \"text/plain\",\n        \"extension\": \"txt\",\n        \"name\": \"original.txt\",\n        \"sha256\": \"6798b7a132f37a0474002dec538ec52bdcd5f7b76e49e52c8a3d2016ca8d1d18\",\n        \"size\": 14,\n    },\n)\n\n# Example JSON printed to standard output\n{\n    # Values provided as arguments\n    \"EventType\": \"FileCopied\",\n    \"EventResult\": \"Success\",\n\n    \"TargetFilePath\": \"/tmp/copied.txt\",\n    \"TargetFileName\": \"copied.txt\",\n    \"TargetFileExtension\": \"txt\",\n    \"TargetFileMimeType\": \"text/plain\",\n    \"TargetFileSHA256\": \"6798b7a132f37a0474002dec538ec52bdcd5f7b76e49e52c8a3d2016ca8d1d18\",\n    \"TargetFileSize\": 14,\n\n    \"SrcFilePath\": \"/tmp/original.txt\",\n    \"SrcFileName\": \"original.txt\",\n    \"SrcFileExtension\": \"txt\",\n    \"SrcFileMimeType\": \"text/plain\",\n    \"SrcFileSHA256\": \"6798b7a132f37a0474002dec538ec52bdcd5f7b76e49e52c8a3d2016ca8d1d18\",\n    \"SrcFileSize\": 14,\n\n    # Calculated / Hard coded fields\n    \"EventStartTime\": \"2025-07-30T11:05:09.406460+00:00\",\n    \"EventSchema\": \"FileEvent\",\n    \"EventSchemaVersion\": \"0.2.1\",\n    \"EventSeverity\": \"Informational\",\n\n    # Taken from Django HttpRequest object\n    \"HttpHost\": \"WebServer.local\",\n    \"SrcIpAddr\": \"192.168.1.101\",\n    \"TargetUrl\": \"https://WebServer.local/steel\",\n    \"TargetUsername\": \"Adrian\"\n\n    # Taken from DBT Platform environment variables\n    \"TargetAppName\": \"export-analytics-frontend\",\n}\n```\n\n#### Account Management event\n\nFollowing the [ASIM User Management Schema](https://learn.microsoft.com/en-us/azure/sentinel/normalization-schema-user-management).\n\n\n```python\n# Example usage\nfrom django_log_formatter_asim.events import log_account_management\n\nlog_account_management(\n    request,\n    event=log_account_management.Event.UserCreated,\n    result=log_account_management.Result.Success,\n    account={\n        \"username\": \"Roger\",\n    },\n)\n\n# Example JSON printed to standard output\n{\n    # Values provided as arguments\n    \"EventType\": \"UserCreated\",\n    \"EventResult\": \"Success\",\n    \"TargetUsername\": \"Roger\",\n\n    # Calculated / Hard coded fields\n    \"EventStartTime\": \"2025-07-30T11:05:09.406460+00:00\",\n    \"EventSchema\": \"UserManagement\",\n    \"EventSchemaVersion\": \"0.1.1\",\n    \"EventSeverity\": \"Informational\",\n\n    # Taken from Django HttpRequest object\n    \"HttpHost\": \"WebServer.local\",\n    \"SrcIpAddr\": \"192.168.1.101\",\n    \"TargetUrl\": \"https://WebServer.local/admin/create-user\",\n    \"ActorUsername\": \"Adrian\"\n\n    # Taken from DBT Platform environment variables\n    \"TargetAppName\": \"export-analytics-frontend\",\n}\n```\n\n## Dependencies\n\nThis package uses [Django IPware](https://github.com/un33k/django-ipware) for IP address capture.\n\nThis package is compatible with [Django User Agents](https://pypi.org/project/django-user-agents) which, when used, will enhance logged user agent information.\n\n## Contributing to the `django-log-formatter-asim` package\n\n### Getting started\n\n1. Clone the repository:\n\n   ```\n   git clone https://github.com/uktrade/django-log-formatter-asim.git \u0026\u0026 cd django-log-formatter-asim\n   ```\n\n2. Install the required dependencies:\n\n   ```\n   pip install poetry \u0026\u0026 poetry install \u0026\u0026 poetry run pre-commit install\n   ```\n\n### Testing\n\n#### Automated testing\n\nRun `poetry run pytest` in the root directory to run all tests.\n\nOr, run `poetry run tox` in the root directory to run all tests for multiple Python versions. See the [`tox` configuration file](tox.ini).\n\n### Publishing\n\nCreate a pull request to update the [CHANGELOG.md](./CHANGELOG.md) and also create a [create a release in GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) for your new version.\n\n1. Acquire API token from [Passman](https://passman.ci.uktrade.digital/secret/cc82a3f7-ddfa-4312-ab56-1ff8528dadc8/).\n   - Request access from the SRE team.\n   - _Note: You will need access to the `platform` group in Passman._\n2. Run `poetry config pypi-token.pypi \u003ctoken\u003e` to add the token to your Poetry configuration.\n\nUpdate the version, as the same version cannot be published to PyPI.\n\n```\npoetry version patch\n```\n\nMore options for the `version` command can be found in the [Poetry documentation](https://python-poetry.org/docs/cli/#version). For example, for a minor version bump: `poetry version minor`.\n\nBuild the Python package.\n\n```\npoetry build\n```\n\nPublish the Python package.\n\n_Note: Make sure your Pull Request (PR) is approved and contains the version upgrade in `pyproject.toml` before publishing the package._\n\n```\npoetry publish\n```\n\nCheck the [PyPI Release history](https://pypi.org/project/django-log-formatter-asim/#history) to make sure the package has been updated.\n\nFor an optional manual check, install the package locally and test everything works as expected.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuktrade%2Fdjango-log-formatter-asim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuktrade%2Fdjango-log-formatter-asim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuktrade%2Fdjango-log-formatter-asim/lists"}