{"id":35067628,"url":"https://github.com/karbunkul/dart_beholder","last_synced_at":"2026-05-22T03:03:37.139Z","repository":{"id":272056818,"uuid":"907070782","full_name":"karbunkul/dart_beholder","owner":"karbunkul","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-23T12:18:55.000Z","size":16,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-23T13:25:32.493Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dart","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/karbunkul.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2024-12-22T18:17:04.000Z","updated_at":"2025-03-23T12:18:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"b14dcc3d-e5c3-4f01-b84e-872bd84af715","html_url":"https://github.com/karbunkul/dart_beholder","commit_stats":null,"previous_names":["karbunkul/dart_beholder"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/karbunkul/dart_beholder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karbunkul%2Fdart_beholder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karbunkul%2Fdart_beholder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karbunkul%2Fdart_beholder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karbunkul%2Fdart_beholder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karbunkul","download_url":"https://codeload.github.com/karbunkul/dart_beholder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karbunkul%2Fdart_beholder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33326656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"online","status_checked_at":"2026-05-22T02:00:06.671Z","response_time":265,"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":[],"created_at":"2025-12-27T11:38:32.714Z","updated_at":"2026-05-22T03:03:37.132Z","avatar_url":"https://github.com/karbunkul.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beholder 👁️\n\nBeholder is a powerful, fully customizable logging library for Dart and Flutter, built with a focus on performance, structured data, and clean architecture. Unlike other solutions, Beholder avoids global singletons in favor of a strictly instance-based approach.\n\n## Key Features 💡\n\n### Instance-Based Architecture\nNo global state. Create independent logger instances for different modules, layers, or environments. This makes testing and isolation effortless.\n\n### Async Lifecycle \u0026 State Guards 🔄\nMany transports (databases, files, network clients) require asynchronous setup. Beholder manages their `init()` and `dispose()` cycles, protecting your system from using uninitialized resources via **State Guards**.\n\n### Advanced Transport Filtering 🛡️\nFine-tune which data each transport handles with precision:\n- **Type Filtering (`allowedTypes` / `ignoredTypes`)**: Control processing based on the data type (e.g., skip `Heartbeat` or only allow `NetworkRequest`).\n- **Tag Filtering (`allowedTags` / `ignoredTags`)**: Filter records based on their string tags. Perfect for isolating \"UI\" logs from \"Network\" logs even if they share the same level.\n- **Synchronous Checks**: Filtering happens instantly before any expensive record processing (like converter execution) begins.\n\n### Smart Placeholders 🧩\nBeholder uses a lazy, high-performance templating system. You can use built-in placeholders or provide custom ones via `ContextPlaceholder`.\n\n**Standard system placeholders (available in every record):**\n- `{logName}`: The name of the logger instance.\n- `{logLevel}`: Numeric representation of the log level (e.g., `100`).\n- `{logLevelName}`: Human-readable level name (e.g., `INFO`).\n- `{logTags}`: String representation of the associated tags.\n- `{logDateTime}`: Local ISO8601 timestamp.\n- `{logDateTimeUtc}`: UTC ISO8601 timestamp.\n- `{logData}`: The main data object, formatted using the matching `LogEntryConverter`.\n- `{logMessage}`: The optional message string from the `LogEntry`.\n\nAll placeholders are resolved **lazily**. For example, `{logData}` will only trigger the converter's `onConvert` function if a transport actually contains this placeholder in its output format.\n\n**Programmatically list all available keys:**\nIf you are building a custom transport and need to know which keys are available:\n```dart\n@override\nFuture\u003cString\u003e log(RecordEntry\u003cObject\u003e record) async {\n  // Print all available placeholders\n  record.placeholder.help();\n  \n  // Use the manager to resolve a specific template\n  return record.placeholder.template('[{logLevelName}] {logData}');\n}\n```\n\n## Performance ⚡\nBeholder v0.9.8 is engineered for high-load applications:\n- **Lazy Evaluation**: Expensive operations, such as formatting complex objects into strings (`logData`), are only performed when a transport actually requests them.\n- **O(1) Converter Lookups**: Finding the right converter for a data type is a constant-time operation thanks to built-in type caching and \"warm-up\" during initialization.\n- **Internal Caching**: Formatted data is computed exactly once per record, even if dispatched to multiple transports.\n- **Zero-Block Dispatch**: Utilizes `Future.value` and `unawaited` to ensure logging never blocks your app's main execution flow.\n\n## Quick Start 🚀\n\n### 1. Configure Options\nDefine your log levels, converters, and transports:\n\n```dart\nfinal class MyOptions extends BeholderOptions\u003cAppTag\u003e {\n  @override\n  int get logLevel =\u003e 0; \n\n  @override\n  List\u003cLogLevel\u003e get levels =\u003e [\n    LogLevel(\n      level: 100,\n      name: 'info',\n      transports: [\n        // Use TransportAdapter for fine-grained control\n        TransportAdapter(\n          transport: ConsoleTransport(),\n          ignoredTypes: [Heartbeat], // Skip technical noise\n          ignoredTags: ['internal', 'sensitive'], // Skip specific tags\n          onLog: (record) =\u003e '[${record.time}] ${record.description}',\n        ),\n      ],\n    ),\n  ];\n  \n  @override\n  List\u003cLogEntryConverter\u003e get converters =\u003e [\n    LogEntryConverter\u003cDateTime\u003e(onConvert: (dt) =\u003e dt.toIso8601String()),\n    LogEntryConverter\u003cUser\u003e(onConvert: (u) =\u003e 'User(id: ${u.id})'),\n  ];\n}\n```\n\n### 2. Create Your Logger\n```dart\nbase class MyLogger extends Beholder\u003cAppTag\u003e {\n  MyLogger() : super(name: 'App', settings: MyOptions());\n\n  void info(Object data, {List\u003cAppTag\u003e? tags}) =\u003e \n      log(entry: LogEntry(data), level: 100, tags: tags);\n}\n```\n\n### 3. Use It ✅\n```dart\nvoid main() async {\n  final logger = MyLogger();\n  \n  // Mandatory initialization for async transports\n  await logger.init();\n\n  logger.info('Application started');\n  logger.info(Heartbeat(), tags: [AppTag.system]); // Ignored by console transport\n\n  // Graceful shutdown\n  await logger.dispose();\n}\n```\n\n## Installation 📦\n\nAdd `beholder` to your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  beholder: ^0.9.8\n```\n\n## License 📄\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarbunkul%2Fdart_beholder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarbunkul%2Fdart_beholder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarbunkul%2Fdart_beholder/lists"}