{"id":28974936,"url":"https://github.com/malekd5/uniusage","last_synced_at":"2026-05-09T05:32:03.150Z","repository":{"id":299229930,"uuid":"1002411887","full_name":"MalekD5/uniusage","owner":"MalekD5","description":"UniUsage is a command-line tool for analyzing user behavior from log files.","archived":false,"fork":false,"pushed_at":"2025-06-17T13:09:40.000Z","size":5236,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-27T17:58:40.981Z","etag":null,"topics":["auto-release","github-actions","gradle","gradle-kotlin-dsl","hyperloglog","java","java17","junit5"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MalekD5.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-06-15T12:24:32.000Z","updated_at":"2025-06-17T13:10:17.000Z","dependencies_parsed_at":"2025-06-15T13:55:23.481Z","dependency_job_id":"1c170664-1b04-438a-9a13-087ab7066510","html_url":"https://github.com/MalekD5/uniusage","commit_stats":null,"previous_names":["malekd5/uniusage"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/MalekD5/uniusage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MalekD5%2Funiusage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MalekD5%2Funiusage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MalekD5%2Funiusage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MalekD5%2Funiusage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MalekD5","download_url":"https://codeload.github.com/MalekD5/uniusage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MalekD5%2Funiusage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32808411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"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":["auto-release","github-actions","gradle","gradle-kotlin-dsl","hyperloglog","java","java17","junit5"],"created_at":"2025-06-24T12:07:39.847Z","updated_at":"2026-05-09T05:32:03.126Z","avatar_url":"https://github.com/MalekD5.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Table of Contents**\n\n- [Installation](#installation)\n- [Commands](#available-commands)\n  - [tophll](#tophll)\n  - [top](#top)\n  - [count](#count)\n- [Problem Description \u0026 Examples](#problem-overview--examples)\n  - [Problem 1](#problem-1--finding-top-k-operations)\n  - [Problem 2](#problem-2--how-do-you-verify-it-works)\n  - [Problem 3](#problem-3--changing-k-easily)\n  - [Problem 4](#problem-4--why-is-it-fast-or-slow)\n\n# UniUsage CLI Tool\n\n\n**UniUsage** is a command-line tool for analyzing user behavior from log files. It provides three core functionalities:\n\n- ✅ Estimate unique user counts per operation using **HyperLogLog** (for large datasets)\n- 🔍 Brute-force count of unique users per operation (for small datasets)\n- 🔢 Count total number of log entries with multithreading\n\n\n## Installation\n\n- **Requirement:** Java **17** or higher\n- No need to run `gradlew build` before running the CLI, the script will do it for you\n\n### Run the CLI\n\non Windows:\n```powershell\n.\\uniusage.bat [command] [options]\n```\n\non Linux/MacOS:\n```bash\n./uniusage.sh [command] [options]\n```\n\n\n## Available Commands\n\n### `tophll`\n\nEstimate top K operations by unique user count using **HyperLogLog**.\n\n**Usage:**\n\non Windows:\n\n```powershell\n.\\uniusage.bat tophll --logfile \u003cpath_to_log_file\u003e [--k \u003ctop_k\u003e] [--precision \u003chll_precision\u003e]\n```\n\non Linux/MacOS:\n\n```bash\n./uniusage.sh tophll --logfile \u003cpath_to_log_file\u003e [--k \u003ctop_k\u003e] [--precision \u003chll_precision\u003e]\n```\n\n**Options:**\n\n- `--logfile` (required): Path to the log file  \n- `--k`, `--top-k`: Number of top operations to display (default: `2`)  \n- `--precision`, `--hll-precision`: HLL precision (default: `18`, ~0.2% standard error)\n\n**Note on Precision**: The higher the precision, the more accurate the estimation, but the slower the computation and the higher the memory usage.\n\n### `top`\n\nBrute-force method to find top K operations by unique users.  \n**Best for small datasets.**\n\n**Usage:**\n\non Windows:\n```powershell\n.\\uniusage.bat top --logfile \u003cpath_to_log_file\u003e [--k \u003ctop_k\u003e]\n```\n\non Linux/MacOS:\n```bash\n./uniusage.sh top --logfile \u003cpath_to_log_file\u003e [--k \u003ctop_k\u003e]\n```\n\n**Options:**\n\n- `--logfile` (required): Path to the log file  \n- `--k`, `--top-k`: Number of top operations to display (default: `2`)\n\n\n### `count`\n\nMultithreaded log processor to count **total number of entries** in the log file.\n\n**Usage:**\n\non Windows:\n```powershell\n.\\uniusage.bat count --logfile \u003cpath_to_log_file\u003e\n```\n\non Linux/MacOS:\n\n```bash\n./uniusage.sh count --logfile \u003cpath_to_log_file\u003e\n```\n\n**Options:**\n\n- `--logfile` (required): Path to the log file\n\n\n## Problem Overview \u0026 Examples\n\nWe are given a log file containing user actions and asked to:\n\n1. Identify the **top K most used operations**.\n2. Determine the **percentage of users** who used each operation.\n3. Ensure **each user is counted once per operation**.\n\n## 🧩 Problem 1 — Finding Top K Operations\n\n\u003e 🧑‍💼 \"Can you tell me the most used two operations and the % of users who use them?\"\n\u003e\n\u003e ✅ Your response: \"Consider it done. Each user will be counted only once per operation.\"\n\n### Two Implemented Solutions\n\n#### 🔬 1. HyperLogLog Algorithm (Recommended for Large Logs)\n\n```powershell\n.\\uniusage.bat tophll --logfile log_file.log\n```\n\n**Sample Output:**\n\n```\nTop 2 operations by unique users with standard error of 0.20%:\n\nOperation \"connect\" is used by 81.23% of our users (2251 users).\nOperation \"filter-changed\" is used by 80.01% of our users (2217 users).\n```\n\n\u003e HLL provides high performance and low memory usage with a small error margin (±0.2%).\n\n\n\n#### 🛠️ 2. Brute Force Algorithm (Accurate for Small/Medium Logs)\n\n```powershell\n.\\uniusage.bat top --logfile log_file.log\n```\n\n**Sample Output:**\n\n```\nOperation \"connect\" is used by 81.23% of our users (2251 users).\nOperation \"filter-changed\" is used by 80.04% of our users (2218 users).\n```\n\n\u003e Ideal for debugging, development, and small-scale datasets.\n\n\n\n## Problem 2 — How Do You Verify It Works?\n\n\u003e 🧑‍💼 \"How do you know your results are correct?\"\n\n- ✅ I created smaller sample logs like `sm_log_file_x.log`\n- 🔎 Manually analyzed them to find expected top operations and percentages\n- 🧪 Ran both brute-force and HLL implementations on the samples\n- ✅ Verified the outputs matched the expected results\n\n\n\n## Problem 3 — Changing K Easily\n\n\u003e 🧑‍💼 \"Can I find the top 3 operations instead of just 2?\"\n\nAbsolutely. Use the `--top-k` flag:\n\n```powershell\n.\\uniusage.bat top --logfile log_file.log --top-k 3\n```\n\n**Sample Output:**\n\n```\nOperation \"connect\" is used by 81.23% of our users (2251 users).\nOperation \"filter-changed\" is used by 80.04% of our users (2218 users).\nOperation \"open-detailed-quotes\" is used by 45.11% of our users (1250 users).\n```\n\n\u003e The CLI is flexible — change `--top-k` to any number you need.\n\n\n\n## Problem 4 — Why is it Fast or Slow?\n\n\u003e 🧑‍💼 \"Why is it slow? Can you make it faster?\"\n\nYes, performance was part of the design. Here's how it’s optimized:\n\n- 🔍 **Brute force** for accuracy in small logs\n- 🧵 **Multithreading** is used for in HLLL implementation\n- 🌀 **HyperLogLog** for large logs with minimal memory overhead\n- ⚙️ Easy to switch between them using CLI flags\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalekd5%2Funiusage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmalekd5%2Funiusage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalekd5%2Funiusage/lists"}