# micropython-loki
[](https://github.com/olivergregorius/micropython_loki/actions/workflows/build.yml)
[](https://pypi.org/project/micropython-loki/)
[](https://github.com/olivergregorius/micropython_loki/blob/HEAD/LICENSE)
[](https://pypi.org/project/micropython-loki/)
## Introduction
Micropython library for sending logs to [Loki](https://grafana.com/oss/loki/)
## Installation
The library can be installed using [upip](https://docs.micropython.org/en/latest/reference/glossary.html#term-upip) or
[mip](https://docs.micropython.org/en/latest/reference/packages.html). Ensure that the device is connected to the network.
### Installation using upip (Micropython < 1.19)
```python
import upip
upip.install('micropython-loki')
```
### Installation using mip (Micropython >= 1.19)
#### Py-file
```python
import mip
mip.install('github:olivergregorius/micropython_loki/micropython_loki.py')
```
#### Cross-compiled mpy-file
**NOTE**: Set the release_version variable accordingly.
```python
import mip
release_version='vX.Y.Z'
mip.install(f'https://github.com/olivergregorius/micropython_loki/releases/download/{release_version}/micropython_loki.mpy')
```
## Usage
This library provides two methods for
1. adding log messages to the stack (`log`) and
2. pushing the logs to a Loki instance (`push_logs`).
**NOTE**: Each log message is applied with the current system's timestamp. Please be sure the RTC of the device is set correctly.
At first the Loki-instance must be initialized providing the Loki base-URL:
```python
from micropython_loki import Loki
loki = Loki('https://loki.example.org:3100')
```
The following additional arguments may be provided:
| Argument | Description | Default |
|--------------------|------------------------------------------------------------------------------------------------------------|------------------|
| log_labels | List of `LogLabel` instances. Each `LogLabel` is a key-value pair to enrich each log message with a label. | [] |
| default_log_level | Set the default log level. Instance of `LogLevel`. | `LogLevel.INFO` |
| timeout | Timeout in seconds for calls against the Loki-API. | 5 |
| max_stack_size | Maximum size of the log stack. If the stack size exceeds this value, the 'oldest' log message is dropped. | 50 |
| min_push_log_level | Minimum log level of log messages to be pushed to Loki. | `LogLevel.DEBUG` |
The following example creates a Loki-instance for calling the Loki-API at 'https://loki.example.org:3100', adding the labels 'app: important-app' and
'version: 1.0.0' to each log message, setting the default log level to 'INFO', setting the timeout to 5 seconds, setting the max stack size to 20 and only
pushing logs to Loki with LogLevel.WARN or LogLevel.ERROR.
```python
from micropython_loki import Loki, LogLabel, LogLevel
loki = Loki('https://loki.example.org:3100', [LogLabel('app', 'important-app'), LogLabel('version', '1.0.0')], LogLevel.INFO, 5, 20, LogLevel.WARN)
```
To add a log message to the log-stack the method `log` is called, it takes the arguments `message` (required) containing the log message and `log_level`
(optional) for setting the log level for that log message:
```python
...
loki.log('Calling do_something')
result = do_something()
if result == 1:
loki.log('Something went wrong', LogLevel.WARN)
...
```
The example above adds one log message of level 'INFO' (as set by default during Loki instantiation, the LogLevel can be omitted in the `log` call) and one log
message of level 'WARN' (in case the value of result is 1).
Convenience methods have been added to simplify adding log messages to the stack:
```python
loki.debug('Message with LogLevel.DEBUG')
loki.info('Message with LogLevel.INFO')
loki.warn('Message with LogLevel.WARN')
loki.error('Message with LogLevel.ERROR')
```
To push the logs to Loki `push_logs` is called, this method takes no arguments:
```python
...
loki.push_logs()
...
```
Raw data
{
"_id": null,
"home_page": "",
"name": "micropython-loki",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Loki,Microcontroller,Micropython,Logging",
"author": "Oliver Gregorius",
"author_email": "oliver@gregorius.dev",
"download_url": "https://files.pythonhosted.org/packages/02/c2/3f5e72c54daf5ef6fbae944372414e09391f4025ce52244c602125f48d04/micropython_loki-1.1.2.tar.gz",
"platform": null,
"description": "# micropython-loki\n\n[](https://github.com/olivergregorius/micropython_loki/actions/workflows/build.yml)\n[](https://pypi.org/project/micropython-loki/)\n[](https://github.com/olivergregorius/micropython_loki/blob/HEAD/LICENSE)\n[](https://pypi.org/project/micropython-loki/)\n\n## Introduction\n\nMicropython library for sending logs to [Loki](https://grafana.com/oss/loki/)\n\n## Installation\n\nThe library can be installed using [upip](https://docs.micropython.org/en/latest/reference/glossary.html#term-upip) or\n[mip](https://docs.micropython.org/en/latest/reference/packages.html). Ensure that the device is connected to the network.\n\n### Installation using upip (Micropython < 1.19)\n\n```python\nimport upip\nupip.install('micropython-loki')\n```\n\n### Installation using mip (Micropython >= 1.19)\n\n#### Py-file\n\n```python\nimport mip\nmip.install('github:olivergregorius/micropython_loki/micropython_loki.py')\n```\n\n#### Cross-compiled mpy-file\n\n**NOTE**: Set the release_version variable accordingly.\n\n```python\nimport mip\nrelease_version='vX.Y.Z'\nmip.install(f'https://github.com/olivergregorius/micropython_loki/releases/download/{release_version}/micropython_loki.mpy')\n```\n\n## Usage\n\nThis library provides two methods for\n\n1. adding log messages to the stack (`log`) and\n2. pushing the logs to a Loki instance (`push_logs`).\n\n**NOTE**: Each log message is applied with the current system's timestamp. Please be sure the RTC of the device is set correctly.\n\nAt first the Loki-instance must be initialized providing the Loki base-URL:\n\n```python\nfrom micropython_loki import Loki\n\nloki = Loki('https://loki.example.org:3100')\n```\n\nThe following additional arguments may be provided:\n\n| Argument | Description | Default |\n|--------------------|------------------------------------------------------------------------------------------------------------|------------------|\n| log_labels | List of `LogLabel` instances. Each `LogLabel` is a key-value pair to enrich each log message with a label. | [] |\n| default_log_level | Set the default log level. Instance of `LogLevel`. | `LogLevel.INFO` |\n| timeout | Timeout in seconds for calls against the Loki-API. | 5 |\n| max_stack_size | Maximum size of the log stack. If the stack size exceeds this value, the 'oldest' log message is dropped. | 50 |\n| min_push_log_level | Minimum log level of log messages to be pushed to Loki. | `LogLevel.DEBUG` |\n\nThe following example creates a Loki-instance for calling the Loki-API at 'https://loki.example.org:3100', adding the labels 'app: important-app' and\n'version: 1.0.0' to each log message, setting the default log level to 'INFO', setting the timeout to 5 seconds, setting the max stack size to 20 and only\npushing logs to Loki with LogLevel.WARN or LogLevel.ERROR.\n\n```python\nfrom micropython_loki import Loki, LogLabel, LogLevel\n\nloki = Loki('https://loki.example.org:3100', [LogLabel('app', 'important-app'), LogLabel('version', '1.0.0')], LogLevel.INFO, 5, 20, LogLevel.WARN)\n```\n\nTo add a log message to the log-stack the method `log` is called, it takes the arguments `message` (required) containing the log message and `log_level`\n(optional) for setting the log level for that log message:\n\n```python\n...\nloki.log('Calling do_something')\nresult = do_something()\n\nif result == 1:\n loki.log('Something went wrong', LogLevel.WARN)\n...\n```\n\nThe example above adds one log message of level 'INFO' (as set by default during Loki instantiation, the LogLevel can be omitted in the `log` call) and one log\nmessage of level 'WARN' (in case the value of result is 1).\n\nConvenience methods have been added to simplify adding log messages to the stack:\n\n```python\nloki.debug('Message with LogLevel.DEBUG')\nloki.info('Message with LogLevel.INFO')\nloki.warn('Message with LogLevel.WARN')\nloki.error('Message with LogLevel.ERROR')\n```\n\nTo push the logs to Loki `push_logs` is called, this method takes no arguments:\n\n```python\n...\nloki.push_logs()\n...\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Micropython library for sending logs to Loki",
"version": "1.1.2",
"split_keywords": [
"loki",
"microcontroller",
"micropython",
"logging"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "aca984f77e43efb81e5c7f183b794b77",
"sha256": "d7f75c6b90df4d1570bdf4b33b74c04ab622516b29cd0eb6a344d2fecd731ae6"
},
"downloads": -1,
"filename": "micropython_loki-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "aca984f77e43efb81e5c7f183b794b77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4028,
"upload_time": "2022-12-16T19:03:57",
"upload_time_iso_8601": "2022-12-16T19:03:57.721079Z",
"url": "https://files.pythonhosted.org/packages/02/c2/3f5e72c54daf5ef6fbae944372414e09391f4025ce52244c602125f48d04/micropython_loki-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-16 19:03:57",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "micropython-loki"
}
JSON