{"id":46269768,"url":"https://github.com/woozymasta/logz","last_synced_at":"2026-03-04T03:01:09.640Z","repository":{"id":325733258,"uuid":"1102207622","full_name":"WoozyMasta/logz","owner":"WoozyMasta","description":"Server-side DayZ mod that implements structured logging (NDJSON) for advanced server analytics and monitoring","archived":false,"fork":false,"pushed_at":"2025-12-17T08:37:38.000Z","size":208,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-20T17:19:56.147Z","etag":null,"topics":["dayz","dayz-mod","enforce-script","logging","monitoring","ndjson","observability","structured-logging"],"latest_commit_sha":null,"homepage":"https://steamcommunity.com/sharedfiles/filedetails/?id=3610709966","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WoozyMasta.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":null,"security":null,"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":"2025-11-23T02:38:45.000Z","updated_at":"2025-12-17T08:37:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/WoozyMasta/logz","commit_stats":null,"previous_names":["woozymasta/logz"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/WoozyMasta/logz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoozyMasta%2Flogz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoozyMasta%2Flogz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoozyMasta%2Flogz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoozyMasta%2Flogz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WoozyMasta","download_url":"https://codeload.github.com/WoozyMasta/logz/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoozyMasta%2Flogz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30070479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T01:03:42.280Z","status":"online","status_checked_at":"2026-03-04T02:00:07.464Z","response_time":59,"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":["dayz","dayz-mod","enforce-script","logging","monitoring","ndjson","observability","structured-logging"],"created_at":"2026-03-04T03:01:06.904Z","updated_at":"2026-03-04T03:01:09.630Z","avatar_url":"https://github.com/WoozyMasta.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LogZ\n\n\u003c!-- markdownlint-disable-next-line MD033 --\u003e\n\u003cimg src=\"logo.png\" alt=\"MetricZ\" align=\"right\" width=\"300\"\u003e\n\nLogZ is a server-side modification for DayZ that implements structured\nlogging in NDJSON (Newline Delimited JSON) format.\n\nThe mod is designed to send server logs to ELK, Loki, Graylog, or\nVictoriaLogs. It brings DevOps Best Practices into the DayZ environment.\n\nUnlike standard text logs (`.log`, `.ADM`), which are impossible to parse\nautomatically, LogZ creates machine-readable events with a fixed structure.\nThis allows you to build dashboards, configure alerts, and quickly search\nfor information.\n\nThis logger is not about errors and exceptions; it is about server\nstatistics and analytics. The main goals are not to spam with noisy events\nbut to provide server administrators with the most important and useful data\nto study player activity and behavior.\n\n\u003e [!WARNING]  \n\u003e **BETA VERSION**\n\u003e\n\u003e This mod is currently in **BETA**.\n\u003e\n\u003e * The log structure, configuration schema, internal API,\n\u003e   and file paths **are subject to change** without backward compatibility.\n\u003e * It is **not recommended for use in production environments**\n\u003e   where data stability is critical.\n\u003e * Please check the changelogs carefully when updating.\n\n\u003c!-- markdownlint-disable-next-line MD033 --\u003e\n\u003cbr clear=\"right\"/\u003e\n\n\u003e [!TIP]  \n\u003e It works best when combined with Prometheus-format metrics using the\n\u003e [MetricZ] mod. MetricZ accumulates updatable metrics in counters, while\n\u003e everything that cannot be ticked as a simple counter is written to the\n\u003e structured log.\n\n## Features\n\n* **NDJSON Format:** Each line is a valid JSON object.\n* **Rich Context:** Logs not just \"who killed whom\", but positions,\n  inventory, distance, projectile type, hit zones, and much more.\n* **Event Coverage:**\n  * Player: Connection, chat, suicide, unconsciousness, actions (gestures,\n    swimming).\n  * Combat: Damage and kills (players, infected, animals).\n  * Transport: Damage, destruction, driver/passengers.\n  * Building \u0026 Items: Interaction, base damage.\n  * Inventory: Pickup, drop, item movement (with filtering).\n  * System events: Triggers, contamination areas, explosions.\n* **Log Rotation:** Built-in file rotation system to prevent disk overflow.\n* **Performance:** Throttling of frequent events (e.g., shooting) and damage\n  thresholds to reduce spam.\n\n\u003e [!NOTE]  \n\u003e The mod is currently under active development.  \n\u003e The log structure, API, methods, and DTOs are subject to change.\n\u003e For this reason, I am not publishing ready-made dashboards yet.\n\n## Installation\n\n1. Install the mod on the server. Subscribe via Workshop or download the PBO\n   from releases. A key is not required for a server-side mod!\n1. Add `-servermod=@LogZ` to the server launch parameters.\n1. Start the server.\n1. The configuration file will be automatically created at\n   `$profile:logz/config.json`.\n1. Logs will be written to `$profile:logz/logs/`.\n\n## Configuration\n\nConfiguration is handled via a JSON file located at `$profile:logz/config.json`.\nChanges require a server restart to take effect.\n\nSee [CONFIG.md](./CONFIG.md) for a detailed description of all parameters.\n\n## Output Examples\n\nExample of a simple event (connection):\n\n```json\n{\"ts\":1763850873,\"uptime_ms\":65049,\"world_time\":1600603200,\"instance\":99,\"level\":\"info\",\"schema\":\"logz-v1beta\",\"world\":\"chernarusplus\",\"event_type\":\"player.session\",\"msg\":\"player connected\",\"object\":{\"name\":\"SurvivorM_Elias\",\"type\":\"player\",\"pos\":[2011.5880126953126,105.49319458007813,3314.195068359375],\"yaw\":-52,\"health\":1.0,\"blood\":1.0,\"shock\":1.0,\"id\":-2065192875,\"player_name\":\"WoozyMasta\",\"steam_id\":\"76561198037610867\"}}\n```\n\nThe same example formatted:\n\n```json\n{\n  \"ts\": 1763850873,\n  \"uptime_ms\": 65049,\n  \"world_time\": 1600603200,\n  \"instance\": 99,\n  \"level\": \"info\",\n  \"schema\": \"logz-v1beta\",\n  \"world\": \"chernarusplus\",\n  \"event_type\": \"player.session\",\n  \"msg\": \"player connected\",\n  \"object\": {\n    \"name\": \"SurvivorM_Elias\",\n    \"type\": \"player\",\n    \"pos\": [\n      2011.5880126953126,\n      105.49319458007813,\n      3314.195068359375\n    ],\n    \"yaw\": -52,\n    \"health\": 1.0,\n    \"blood\": 1.0,\n    \"shock\": 1.0,\n    \"id\": -2065192875,\n    \"player_name\": \"WoozyMasta\",\n    \"steam_id\": \"76561198037610867\"\n  }\n}\n```\n\n## Log Collection \u0026 Labels\n\nLogZ outputs NDJSON, which is natively supported by most log collectors.  \nWhen configuring your collector, you should extract specific fields\nfrom the root DTO to use as indexed labels (or tags).\n\nRecommended Labels (Low Cardinality):\n\n* `instance`: Server ID (essential for multi-server setups).\n* `world`: Map name (e.g., `chernarusplus`).\n* `level`: Severity (`info`, `warn`, `error`, etc.).\n* `event_type`: The specific event category\n  (e.g., `player.kill`, `transport.hit`).\n\nAlways map the `ts` field (Unix epoch seconds) to the log timestamp to\nensure accurate timing in your backend.\n\n### Promtail (Loki) Example\n\n```yaml\nscrape_configs:\n  - job_name: dayz_logz\n    static_configs:\n      - targets:\n          - localhost\n        labels:\n          job: dayz_logz\n          __path__: .../dayz-server/profiles/logz.ndjson\n    pipeline_stages:\n      - json:\n          expressions:\n            ts: ts\n            level: level\n            instance: instance\n            world: world\n            event_type: event_type\n      - labels:\n          level:\n          instance:\n          world:\n          event_type:\n      - timestamp:\n          source: ts\n          format: Unix\n```\n\n### Fluent Bit Example\n\n```ini\n[INPUT]\n  Name     tail\n  Path     .../dayz-server/profiles/logz.ndjson\n  Parser   json\n  Tag      dayz.logz\n\n[FILTER]\n  Name         parser\n  Match        dayz.logz\n  Key_Name     log\n  Parser       json\n  Reserve_Data On\n\n[OUTPUT]\n  Name    es\n  Match   dayz.logz\n  # ... your elastic/loki config ...\n  # Ensure 'ts' is mapped to Time_Key if needed\n```\n\n## Technical Details (and a bit of pain)\n\nDayZ uses Enforce Script, and the built-in `JsonSerializer` has fatal flaws:\nit lacks polymorphism support and cannot exclude empty fields (`omitempty`).\n\nTherefore, **LogZ** uses a hybrid approach:\n\n1. There is a root DTO containing basic fields (`ts`, `level`, `msg`).\n2. All additional data (`object`, `victim`, `attacker`, `stats`) are\n   serialized separately into JSON strings from various prepared DTOs.\n3. The final string is assembled by concatenating additional data and\n   inserting it into the root DTO.\n\nThis is a \"crutch\" (workaround), but it is necessary to obtain valid, flat,\nand readable JSON without nested escaped strings, which log collectors like\nFluentBit or PromTail can easily digest.\n\n## Mod Support\n\nThe mod has built-in support for popular modifications:\n\n* **[DayZ-Expansion-AI]**:\n  Correctly identifies eAI bots. Damage events on them are logged as\n  `CREATURE_HIT`/`KILL` instead of `PLAYER_HIT` to avoid spoiling live\n  player statistics.\n* **[MetricZ]**:\n  Exports Prometheus metrics about the logger's operation:\n  * `dayz_metricz_logz_processing_seconds_total` — time spent processing\n    logs.\n  * `dayz_metricz_logz_events_total` — event counter by levels (Info,\n    Warn, Error, etc.).\n\n## For Developers\n\nIf you want to use the LogZ API in your mod to send custom events, check out\n[INTEGRATION.md](./INTEGRATION.md).\n\nCall example:\n\n```c\nLogZ.Info(\"Custom event message\", LogZ_Event.SYSTEM_MISSION);\n```\n\n## 👉 [Support Me](https://gist.github.com/WoozyMasta/7b0cabb538236b7307002c1fbc2d94ea)\n\nIf this mod saved you hours of analytics or helped catch a cheater or abuser,\nplease consider supporting me.  \nAt the very least, a Like and Subscribe on the [LogZ] Steam Workshop\npage would be greatly appreciated!\n\n\u003c!-- Links ---\u003e\n[LogZ]: https://steamcommunity.com/sharedfiles/filedetails/?id=3610709966\n[MetricZ]: https://steamcommunity.com/sharedfiles/filedetails/?id=3594119002\n[DayZ-Expansion-AI]: https://steamcommunity.com/sharedfiles/filedetails/?id=2792982069\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoozymasta%2Flogz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwoozymasta%2Flogz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoozymasta%2Flogz/lists"}