{"id":28829295,"url":"https://github.com/ballerina-platform/module-ballerina-log","last_synced_at":"2026-03-14T18:10:27.690Z","repository":{"id":36981634,"uuid":"288615335","full_name":"ballerina-platform/module-ballerina-log","owner":"ballerina-platform","description":"Ballerina log Module","archived":false,"fork":false,"pushed_at":"2025-06-14T02:13:54.000Z","size":2215,"stargazers_count":111,"open_issues_count":0,"forks_count":39,"subscribers_count":69,"default_branch":"master","last_synced_at":"2025-06-14T03:21:10.640Z","etag":null,"topics":["ballerina","debug","error","hacktoberfest","integration","log","print","warning","wso2"],"latest_commit_sha":null,"homepage":"","language":"Ballerina","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ballerina-platform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-19T02:38:48.000Z","updated_at":"2025-06-14T02:13:56.000Z","dependencies_parsed_at":"2023-10-04T10:31:39.489Z","dependency_job_id":"b384e75b-22ea-457a-9855-c63f429cc364","html_url":"https://github.com/ballerina-platform/module-ballerina-log","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/ballerina-platform/module-ballerina-log","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-log","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-log/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-log/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-log/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ballerina-platform","download_url":"https://codeload.github.com/ballerina-platform/module-ballerina-log/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-log/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260690958,"owners_count":23047106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ballerina","debug","error","hacktoberfest","integration","log","print","warning","wso2"],"created_at":"2025-06-19T05:12:44.730Z","updated_at":"2026-03-14T18:10:27.682Z","avatar_url":"https://github.com/ballerina-platform.png","language":"Ballerina","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ballerina Log Library\n\n  [![Build](https://github.com/ballerina-platform/module-ballerina-log/actions/workflows/build-timestamped-master.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-log/actions/workflows/build-timestamped-master.yml)\n  [![codecov](https://codecov.io/gh/ballerina-platform/module-ballerina-log/branch/master/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/module-ballerina-log)\n  [![Trivy](https://github.com/ballerina-platform/module-ballerina-log/actions/workflows/trivy-scan.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-log/actions/workflows/trivy-scan.yml)\n  [![GraalVM Check](https://github.com/ballerina-platform/module-ballerina-log/actions/workflows/build-with-bal-test-graalvm.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-log/actions/workflows/build-with-bal-test-graalvm.yml)\n  [![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerina-log.svg)](https://github.com/ballerina-platform/module-ballerina-log/commits/master)\n  [![Github issues](https://img.shields.io/github/issues/ballerina-platform/ballerina-standard-library/module/log.svg?label=Open%20Issues)](https://github.com/ballerina-platform/ballerina-standard-library/labels/module%2Flog)\n\nThis library provides APIs to log information when running applications, with support for contextual logging, configurable log levels, formats, destinations, and key-value context.\n\nA sample log message logged from the `foo` module would look as follows:\n\n```bash\ntime = 2021-05-12T11:20:29.362+05:30 level = ERROR module = myorg/foo message = \"Something went wrong\"\n```\n\n## Log Levels\n\nThe log module supports four log levels, in order of priority:\n\n1. `ERROR`\n2. `WARN`\n3. `INFO`\n4. `DEBUG`\n\nBy default, only `INFO` and higher level logs are logged. The log level can be configured globally or per module in the `Config.toml` file:\n\n```toml\n[ballerina.log]\nlevel = \"DEBUG\" # or INFO, WARN, ERROR\n```\n\nPer-module log level:\n\n```toml\n[[ballerina.log.modules]]\nname = \"[ORG_NAME]/[MODULE_NAME]\"\nlevel = \"[LOG_LEVEL]\"\n```\n\n## Logging API\n\nLog messages at different levels using:\n\n```ballerina\nlog:printDebug(\"debug log\");\nlog:printError(\"error log\");\nlog:printInfo(\"info log\");\nlog:printWarn(\"warn log\");\n```\n\nYou can also log errors and add contextual key-value pairs (including function pointers and templates):\n\n```ballerina\nlog:printError(\"error log with cause\", err);\nlog:printInfo(\"info log\", id = 845315, name = \"foo\", successful = true);\n```\n\nSample output (LogFmt):\n\n```log\ntime=2025-08-20T08:49:05.484+05:30 level=INFO module=\"\" message=\"info log\" id=845315 name=\"foo\" successful=true\n```\n\n## Log Output and Format\n\nBy default, logs are written to the `stderr` stream in `logfmt` format. You can configure the output format and destinations in `Config.toml`:\n\n```toml\n[ballerina.log]\nformat = \"json\" # or \"logfmt\"\n\n[[ballerina.log.destinations]]\ntype = \"stderr\" # or \"stdout\"\n\n[[ballerina.log.destinations]]\npath = \"./logs/app.log\"\n```\n\nSample output (JSON):\n\n```json\n{\"time\":\"2025-08-20T11:26:00.021+05:30\", \"level\":\"INFO\", \"module\":\"myorg/foo\", \"message\":\"Authenticating user\"}\n```\n\n\u003e **Note:**\n\u003e\n\u003e - Destination types can be `stderr`, `stdout`, or `file`. File Destination must point to a path with a `.log` extension.\n\u003e - The deprecated `log:setOutputFile()` should be avoided; use configuration instead.\n\n## Log Rotation\n\nThe log module supports automatic log rotation to manage log file growth in production environments. You can configure rotation based on file size, time, or both:\n\n```toml\n[[ballerina.log.destinations]]\ntype = \"file\"\npath = \"./logs/app.log\"\n\n[ballerina.log.destinations.rotation]\npolicy = \"BOTH\"         # SIZE_BASED, TIME_BASED, or BOTH\nmaxFileSize = 10485760  # 10MB in bytes\nmaxAge = 86400       # 24 hours in seconds\nmaxBackupFiles = 7      # Keep 7 backup files\n```\n\nOr configure programmatically:\n\n```ballerina\nlog:Logger logger = check log:fromConfig(\n    destinations = [\n        {\n            'type: log:FILE,\n            path: \"./logs/app.log\",\n            rotation: {\n                policy: log:BOTH,\n                maxFileSize: 10485760,  // 10MB\n                maxAge: 86400,        // 24 hours\n                maxBackupFiles: 7\n            }\n        }\n    ]\n);\n```\n\nWhen rotation occurs, backup files are created with timestamps (e.g., `app-20251209-143022.log`). Old backups beyond `maxBackupFiles` are automatically deleted.\n\n## Root Context\n\nYou can add a default context to all log messages:\n\n```toml\n[ballerina.log]\nkeyValues = {env = \"prod\", nodeId = \"delivery-svc-001\"}\n```\n\n## Contextual Logging\n\nThe log module supports contextual logging, allowing you to create loggers with additional context or unique configurations.\n\n- **Root Logger:** The default logger, accessed via `log:root()`.\n- **Child Logger with Context:**\n\n    ```ballerina\n    log:Logger parentLogger = log:root();\n    log:Logger childLogger = parentLogger.withContext(\"userId\": \"12345\", \"requestId\": \"abcde\");\n    childLogger.printInfo(\"User logged in\");\n    ```\n\n    The log message will include the additional context.\n\n- **Logger with Unique Configuration:**\n\n    ```ballerina\n    log:Config auditLogConfig = {\n            level: log:INFO,\n            format: \"json\",\n            destinations: [\"./logs/audit.log\"]\n    };\n    log:Logger auditLogger = log:fromConfig(auditLogConfig);\n    auditLogger.printInfo(\"Hello World from the audit logger!\");\n    ```\n\nFor more details and advanced usage, see the module specification and API documentation.\n\n## Sensitive Data Masking\n\nThe log module provides capabilities to mask sensitive data in log messages to maintain data privacy and security when dealing with personally identifiable information (PII) or other sensitive data.\n\n\u003e **Note**: By default, sensitive data masking is disabled. Enable it in `Config.toml`:\n\u003e\n\u003e ```toml\n\u003e [ballerina.log]\n\u003e enableSensitiveDataMasking = true\n\u003e ```\n\u003e\n\u003e Or configure it per logger:\n\u003e\n\u003e ```ballerina\n\u003e log:Config secureConfig = {\n\u003e     enableSensitiveDataMasking: true\n\u003e };\n\u003e log:Logger secureLogger = log:fromConfig(secureConfig);\n\u003e ```\n\n### Sensitive Data Annotation\n\nUse the `@log:Sensitive` annotation to mark fields in records as sensitive. When such fields are logged, their values will be excluded or masked:\n\n```ballerina\nimport ballerina/log;\n\ntype User record {\n    string id;\n    @log:Sensitive\n    string password;\n    string name;\n};\n\npublic function main() {\n    User user = {id: \"U001\", password: \"mypassword\", name: \"John Doe\"};\n    log:printInfo(\"user details\", user = user);\n}\n```\n\nOutput (with masking enabled):\n\n```log\ntime=2025-08-20T09:15:30.123+05:30 level=INFO module=\"\" message=\"user details\" user={\"id\":\"U001\",\"name\":\"John Doe\"}\n```\n\n### Masking Strategies\n\nConfigure masking strategies using the `strategy` field:\n\n```ballerina\nimport ballerina/log;\n\nisolated function maskString(string input) returns string {\n    if input.length() \u003c= 2 {\n        return \"****\";\n    }\n    return input.substring(0, 1) + \"****\" + input.substring(input.length() - 1);\n}\n\ntype User record {\n    string id;\n    @log:Sensitive {\n        strategy: {\n            replacement: \"****\"\n        }   \n    }\n    string password;\n    @log:Sensitive {\n        strategy: {\n            replacement: maskString\n        }\n    }\n    string ssn;\n    string name;\n};\n```\n\n### Masked String Function\n\nUse `log:toMaskedString()` to get the masked version of a value for custom logging implementations:\n\n```ballerina\nUser user = {id: \"U001\", password: \"mypassword\", name: \"John Doe\"};\nstring maskedUser = log:toMaskedString(user);\nio:println(maskedUser); // {\"id\":\"U001\",\"name\":\"John Doe\"}\n```\n\n## Build from the source\n\n### Set up the prerequisites\n\n1. Download and install Java SE Development Kit (JDK) version 21 (from one of the following locations).\n\n   - [Oracle](https://www.oracle.com/java/technologies/downloads/)\n   - [OpenJDK](https://adoptium.net/)\n\n   \u003e **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK.\n\n2. Export Github Personal access token with read package permissions as follows,\n\n    ```console\n    export packageUser=\u003cUsername\u003e\n    export packagePAT=\u003cPersonal access token\u003e   \n    ```  \n\n### Build the source\n\nExecute the commands below to build from source.\n\n1. To build the package:\n\n    ```console\n    ./gradlew clean build\n    ```\n\n2. To run the tests:\n\n    ```console\n    ./gradlew clean test\n    ```\n\n3. To run a group of tests\n\n    ```console\n    ./gradlew clean test -Pgroups=\u003ctest_group_names\u003e\n    ```\n\n4. To build the without the tests:\n\n    ```console\n    ./gradlew clean build -x test\n    ```\n\n5. To debug package implementation:\n\n    ```console\n    ./gradlew clean build -Pdebug=\u003cport\u003e\n    ```\n\n6. To debug with Ballerina language:\n\n    ```console\n    ./gradlew clean build -PbalJavaDebug=\u003cport\u003e\n    ```\n\n7. Publish the generated artifacts to the local Ballerina central repository:\n\n    ```console\n    ./gradlew clean build -PpublishToLocalCentral=true\n    ```\n\n8. Publish the generated artifacts to the Ballerina central repository:\n\n    ```console\n    ./gradlew clean build -PpublishToCentral=true\n    ```\n\n## Contribute to Ballerina\n\nAs an open source project, Ballerina welcomes contributions from the community.\n\nFor more information, go to the [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md).\n\n## Code of conduct\n\nAll contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct).\n\n## Useful links\n\n- Chat live with us via our [Discord server](https://discord.gg/ballerinalang).\n- Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.\n- For more information go to the [`log` library](https://lib.ballerina.io/ballerina/log/latest).\n- For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/swan-lake/learn/by-example/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fballerina-platform%2Fmodule-ballerina-log","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fballerina-platform%2Fmodule-ballerina-log","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fballerina-platform%2Fmodule-ballerina-log/lists"}