{"id":8911,"library":"cosl","title":"COS Lite Charm Utilities","description":"COS Lite (Charmed Observability Stack Lite) library provides helper methods and utilities for Juju charm developers to integrate with the COS Lite ecosystem. It offers tools for defining metrics, alerts, dashboards, and managing COS integrations within a charm. The current version is 1.9.1, and it maintains a frequent release cadence with minor updates and bug fixes, typically releasing every few weeks or months.","status":"active","version":"1.9.1","language":"en","source_language":"en","source_url":"https://github.com/canonical/cos-lib","tags":["juju","charm","observability","cos","canonical","metrics","alerts","dashboards","operator"],"install":[{"cmd":"pip install cosl","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for typical usage within Juju charms, as 'cosl' classes like `COSIntegration` depend on 'ops.charm.CharmBase'.","package":"ops","optional":false}],"imports":[{"symbol":"COSIntegration","correct":"from cosl.integrator import COSIntegration"},{"symbol":"Rules","correct":"from cosl.rules import Rules"},{"symbol":"COSChecker","correct":"from cosl.checker import COSChecker"}],"quickstart":{"code":"from ops.charm import CharmBase # Required for actual COSIntegration usage\nfrom cosl.integrator import COSIntegration\nfrom cosl.rules import Rules\n\n# The 'cosl' library is primarily designed to be used within Juju charms.\n\n# 1. Basic usage: Defining observability rules\n# The Rules object encapsulates Prometheus/Grafana rules.\ntry:\n    # Rules are defined as a dictionary, typically loaded from YAML.\n    example_rules_content = {\n        \"groups\": [\n            {\n                \"name\": \"example_group\",\n                \"rules\": [\n                    {\"alert\": \"MyHighCPU\", \"expr\": \"node_cpu_usage_total > 0.9\", \"for\": \"5m\"},\n                    {\"record\": \"job:cpu_usage_rate:avg1m\", \"expr\": \"rate(node_cpu_seconds_total[1m])\"}\n                ]\n            }\n        ]\n    }\n    my_rules = Rules(content=example_rules_content)\n    print(f\"Successfully created a Rules object:\")\n    print(my_rules.content)\nexcept Exception as e:\n    print(f\"Error creating Rules object: {e}\")\n\n# 2. Advanced usage: Integrating with COS Lite in a Juju charm\n# The COSIntegration class requires a 'CharmBase' instance from the 'ops' library.\n# This part is illustrative and needs to be run within a Juju charm's context\n# (e.g., in a charm's __init__.py or a Juju 'ops' test harness).\n\n# class MyCOSCharm(CharmBase):\n#     def __init__(self, framework):\n#         super().__init__(framework)\n#         self.cos = COSIntegration(self) # 'self' is the CharmBase instance\n#         # You would then use self.cos to add rules, dashboards, etc.\n#         # For example: self.cos.add_rules(my_rules)\n#         self.framework.observe(self.cos.on.metrics_alert_rules_changed, self._on_rules_changed)\n#\n#     def _on_rules_changed(self, event):\n#         print(f\"COS rules changed event detected for: {event.rules_path}\")\n\nprint(\"\\nTo use COSIntegration, you need a Juju charm context (from 'ops' library).\")\nprint(\"See the commented-out code above for an example of how it's typically used.\")","lang":"python","description":"This quickstart demonstrates how to define observability rules using the `Rules` class and illustrates the typical integration pattern of `COSIntegration` within a Juju charm. Note that `COSIntegration` requires an instance of `ops.charm.CharmBase` and a running Juju environment or a test harness to be fully functional."},"warnings":[{"fix":"Consult the `cosl` source code or documentation for the updated method signature and adjust calls accordingly.","message":"The signature of `DashboardPath40UID.generate` changed in version 1.3.2. Code directly calling this method with the old signature will break.","severity":"breaking","affected_versions":"<=1.3.1"},{"fix":"Avoid direct calls to `_resolve_against_charm_dir` on `COSChecker` instances. Use officially exposed methods for path resolution or manage paths explicitly.","message":"The internal `_resolve_against_charm_dir` method was removed from `COSChecker` in version 1.6.0. Although prefixed with `_`, it was sometimes used by charm developers.","severity":"breaking","affected_versions":"<1.6.0"},{"fix":"Ensure `cosl` is used within a Juju charm's `CharmBase` subclass or a mocked `ops` test harness environment. Install `ops` via `pip install ops`.","message":"The `cosl` library, particularly its `COSIntegration` class, is tightly coupled with the Juju Operator Framework ('ops' library) and is designed for use within Juju charms. Attempting to use `COSIntegration` outside of a `CharmBase` context will result in errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install cosl` to install the library.","cause":"The 'cosl' library is not installed in your Python environment.","error":"ModuleNotFoundError: No module named 'cosl'"},{"fix":"Update your code to match the new signature of `DashboardPath40UID.generate` as introduced in `cosl` 1.3.2 and later. Check the `cosl` GitHub repository for the current method definition.","cause":"You are calling `DashboardPath40UID.generate` with an incorrect number or type of arguments, likely due to a breaking change in its signature in `cosl` version 1.3.2.","error":"TypeError: DashboardPath40UID.generate() missing X required positional arguments"},{"fix":"Remove any direct calls to `_resolve_against_charm_dir` on `COSChecker` instances. Review charm logic to use alternative, supported methods for resolving charm-specific paths.","cause":"You are attempting to access a method (`_resolve_against_charm_dir`) that was removed from `COSChecker` in `cosl` version 1.6.0.","error":"AttributeError: 'COSChecker' object has no attribute '_resolve_against_charm_dir'"}]}