COS Lite Charm Utilities

1.9.1 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'cosl'
```
cause The 'cosl' library is not installed in your Python environment.

fix Run `pip install cosl` to install the library.
```
TypeError: DashboardPath40UID.generate() missing X required positional arguments
```
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.

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.
```
AttributeError: 'COSChecker' object has no attribute '_resolve_against_charm_dir'
```
cause You are attempting to access a method (`_resolve_against_charm_dir`) that was removed from `COSChecker` in `cosl` version 1.6.0.

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.

Warnings

breaking The signature of `DashboardPath40UID.generate` changed in version 1.3.2. Code directly calling this method with the old signature will break.
Fix: Consult the `cosl` source code or documentation for the updated method signature and adjust calls accordingly.
breaking 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.
Fix: Avoid direct calls to `_resolve_against_charm_dir` on `COSChecker` instances. Use officially exposed methods for path resolution or manage paths explicitly.
gotcha 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.
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`.

Install

pip install cosl Install latest version

Imports

COSIntegration

from cosl.integrator import COSIntegration

Rules
```
from cosl.rules import Rules
```
COSChecker
```
from cosl.checker import COSChecker
```

Quickstart

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.

from ops.charm import CharmBase # Required for actual COSIntegration usage
from cosl.integrator import COSIntegration
from cosl.rules import Rules

# The 'cosl' library is primarily designed to be used within Juju charms.

# 1. Basic usage: Defining observability rules
# The Rules object encapsulates Prometheus/Grafana rules.
try:
    # Rules are defined as a dictionary, typically loaded from YAML.
    example_rules_content = {
        "groups": [
            {
                "name": "example_group",
                "rules": [
                    {"alert": "MyHighCPU", "expr": "node_cpu_usage_total > 0.9", "for": "5m"},
                    {"record": "job:cpu_usage_rate:avg1m", "expr": "rate(node_cpu_seconds_total[1m])"}
                ]
            }
        ]
    }
    my_rules = Rules(content=example_rules_content)
    print(f"Successfully created a Rules object:")
    print(my_rules.content)
except Exception as e:
    print(f"Error creating Rules object: {e}")

# 2. Advanced usage: Integrating with COS Lite in a Juju charm
# The COSIntegration class requires a 'CharmBase' instance from the 'ops' library.
# This part is illustrative and needs to be run within a Juju charm's context
# (e.g., in a charm's __init__.py or a Juju 'ops' test harness).

# class MyCOSCharm(CharmBase):
#     def __init__(self, framework):
#         super().__init__(framework)
#         self.cos = COSIntegration(self) # 'self' is the CharmBase instance
#         # You would then use self.cos to add rules, dashboards, etc.
#         # For example: self.cos.add_rules(my_rules)
#         self.framework.observe(self.cos.on.metrics_alert_rules_changed, self._on_rules_changed)
#
#     def _on_rules_changed(self, event):
#         print(f"COS rules changed event detected for: {event.rules_path}")

print("\nTo use COSIntegration, you need a Juju charm context (from 'ops' library).")
print("See the commented-out code above for an example of how it's typically used.")

view raw JSON →