# gcp-lolo
<p align="center">
<img width="250" src="logo.png">
</p>
**GCP** Cloud **Lo**gging Python **lo**gger
The idea behind this package is to provide the simplest way to log messages to Google Cloud Logging, without having to worry about the details of setting up the Google Cloud Logging client and/or affecting the current application structure.
## Installation
```bash
pip install gcp-lolo
```
## Usage
### #1: Using a python logger
The recommended and idiomatic way to use this package is to create a logging configuration and initialize a logger in your application and in any other sub module(s) as per [Python's Logging HOWTO](https://docs.python.org/3/howto/logging.html).
#### Defining the logging configuration via a INI file
1. Create a file `logging.ini` in your project root folder with the following content:
```ini
[loggers]
keys=root
[handlers]
keys=gcp_handler
[formatters]
keys=
[logger_root]
level=INFO
handlers=gcp_handler
[handler_gcp_handler]
class=gcp_lolo.GCPLoggingHandler
level=DEBUG
kwargs={"name": "my-test-app", "gcp_credentials_path": "./gcp_credentials.json"}
```
2. In your application code, initialize the logger as follows:
```python
import logging
from logging.config import fileConfig
fileConfig('logging.ini')
logger = logging.getLogger(__name__)
# use the logger as usual
logger.debug('Unuseful message in production')
logger.info('This is an info message')
logger.warning('This is a warning')
logger.error('This is an error')
```
#### Defining the logging configuration via the dictConfig method
With the [dictConfig](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig) method you are able to arrange the configuration as you wish.
In the following example, the configuration is written in YAML.
1. Write the configuration in a `logging.yaml` file:
```yaml
version: 1
disable_existing_loggers: false
handlers:
gcp_handler:
class: gcp_lolo.GCPLoggingHandler
level: INFO
name: my-test-app
gcp_credentials_path: "./gcp_credentials.json"
# gcp_credentials_json: "{somecredentialshere}" # alternative to gcp_credentials_path
loggers:
root:
level: INFO
handlers: [gcp_handler]
```
2. In your application code, initialize the logger as follows:
```python
import logging
import logging.config
import yaml
with open('logging.yaml', 'r') as f:
config = yaml.safe_load(f.read())
logging.config.dictConfig(config)
logger = logging.getLogger(__name__)
# use the logger as usual
logger.debug('Unuseful message in production')
logger.info('This is an info message')
logger.warning('This is a warning')
logger.error('This is an error')
```
Of course, please remember to install `PyYAML` to be able to read the YAML configuration file.
### #2: Redirect stdout to GCP Logging
This method is recommended when you have a lot of code that uses `print` and `raise` statements, and you don't want to change it.
```python
from gcp_lolo import setup_gcp_logging
setup_gcp_logging('my-logger')
print('This is a test message')
raise Exception('This is a test exception')
```
⚠ **Important**: This method will NOT work in case of any submodules that initialize their own logger. In that case, you should use the first method instead.
## Authentication
As the package exports logs on GCP Logging, you need some GCP credentials. You can provide them in the following ways:
1. By setting either one of the following environment variables:
- `GOOGLE_APPLICATION_CREDENTIALS`: the path to the local GCP credentials file, or
- `GCP_CREDENTIALS_JSON`: a string containing the GCP credentials JSON
2. By passing the one of the following parameters to the `GCPLoggingHandler` class:
- `gcp_credentials_path`: the path to the local GCP credentials file, or
- `gcp_credentials_json`: a string containing the GCP credentials JSON
## Examples
For more examples, see the [examples](./examples) folder.
## Additional Information
### Multiple Handlers
**Please note**: by default, gcp-lolo will NOT print anything to the console. If you want to print logs to the stdout as well, you can add another handler to the logger.
The following is an example of a `logging.ini` file that uses two different handlers:
```ini
[loggers]
keys=root
[handlers]
keys=gcp_handler,console_handler
[formatters]
keys=stdOutMessageFormatter
[logger_root]
level=INFO
handlers=gcp_handler,console_handler
[handler_gcp_handler]
class=gcp_lolo.GCPLoggingHandler
level=INFO
kwargs={"name": "my-app-with-multiple-logging-handlers", "gcp_credentials_path": "./gcp_credentials.json"}
[handler_console_handler]
class=logging.StreamHandler
level=DEBUG
formatter=stdOutMessageFormatter
[formatter_stdOutMessageFormatter]
format=%(asctime)s - %(levelname)s - %(name)s - %(message)s
```
Of course, this applies to any other logging configuration method you may be using.
### Labeling messages
You can add labels to your messages by passing a `labels` dictionary to the `kwargs` of the `GCPLoggingHandler` in the `logging.ini` file.
Example (pay attention to the `handler_gcp_handler` kwargs):
```ini
[loggers]
keys=root
[handlers]
keys=gcp_handler
[formatters]
keys=
[logger_root]
level=INFO
handlers=gcp_handler
[handler_gcp_handler]
class=gcp_lolo.GCPLoggingHandler
level=DEBUG
kwargs={"name": "my-test-app", "gcp_credentials_path": "./gcp_credentials.json", "labels": {"environment": "staging", "app_version": "1.0.0"}}
```
## Reference
- [Google Cloud Logging](https://cloud.google.com/logging)
- [Google Cloud Logging Python Client](https://cloud.google.com/logging/docs/reference/libraries#client-libraries-install-python)
## License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
## Contributing
Contributions are welcome! Please open an issue or submit a pull request.
Raw data
{
"_id": null,
"home_page": "https://github.com/qurami/gcp-lolo",
"name": "gcp-lolo",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "logging, GCP, Cloud Logging",
"author": "Gianfranco Reppucci, ufirst",
"author_email": "gianfranco.reppucci@ufirst.com",
"download_url": "https://files.pythonhosted.org/packages/71/8a/c17537c827528e2a037d9c94a3c056f0252f7317f3d27c5fb646f0dd53e6/gcp_lolo-2.0.2.tar.gz",
"platform": null,
"description": "# gcp-lolo\n\n<p align=\"center\">\n <img width=\"250\" src=\"logo.png\">\n</p>\n\n**GCP** Cloud **Lo**gging Python **lo**gger\n\nThe idea behind this package is to provide the simplest way to log messages to Google Cloud Logging, without having to worry about the details of setting up the Google Cloud Logging client and/or affecting the current application structure.\n\n## Installation\n\n```bash\npip install gcp-lolo\n```\n\n## Usage\n\n### #1: Using a python logger\n\nThe recommended and idiomatic way to use this package is to create a logging configuration and initialize a logger in your application and in any other sub module(s) as per [Python's Logging HOWTO](https://docs.python.org/3/howto/logging.html).\n\n#### Defining the logging configuration via a INI file\n\n1. Create a file `logging.ini` in your project root folder with the following content:\n\n```ini\n[loggers]\nkeys=root\n\n[handlers]\nkeys=gcp_handler\n\n[formatters]\nkeys=\n\n[logger_root]\nlevel=INFO\nhandlers=gcp_handler\n\n[handler_gcp_handler]\nclass=gcp_lolo.GCPLoggingHandler\nlevel=DEBUG\nkwargs={\"name\": \"my-test-app\", \"gcp_credentials_path\": \"./gcp_credentials.json\"}\n```\n\n2. In your application code, initialize the logger as follows:\n\n```python\nimport logging\nfrom logging.config import fileConfig\n\nfileConfig('logging.ini')\nlogger = logging.getLogger(__name__)\n\n# use the logger as usual\nlogger.debug('Unuseful message in production')\nlogger.info('This is an info message')\nlogger.warning('This is a warning')\nlogger.error('This is an error')\n```\n\n#### Defining the logging configuration via the dictConfig method\n\nWith the [dictConfig](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig) method you are able to arrange the configuration as you wish.\n\nIn the following example, the configuration is written in YAML.\n\n1. Write the configuration in a `logging.yaml` file:\n\n```yaml\nversion: 1\ndisable_existing_loggers: false\nhandlers:\n gcp_handler:\n class: gcp_lolo.GCPLoggingHandler\n level: INFO\n name: my-test-app\n gcp_credentials_path: \"./gcp_credentials.json\"\n # gcp_credentials_json: \"{somecredentialshere}\" # alternative to gcp_credentials_path\nloggers:\n root:\n level: INFO\n handlers: [gcp_handler]\n```\n\n2. In your application code, initialize the logger as follows:\n\n```python\nimport logging\nimport logging.config\nimport yaml\n\nwith open('logging.yaml', 'r') as f:\n config = yaml.safe_load(f.read())\n logging.config.dictConfig(config)\n\nlogger = logging.getLogger(__name__)\n\n# use the logger as usual\nlogger.debug('Unuseful message in production')\nlogger.info('This is an info message')\nlogger.warning('This is a warning')\nlogger.error('This is an error')\n```\n\nOf course, please remember to install `PyYAML` to be able to read the YAML configuration file.\n\n### #2: Redirect stdout to GCP Logging\n\nThis method is recommended when you have a lot of code that uses `print` and `raise` statements, and you don't want to change it.\n\n```python\nfrom gcp_lolo import setup_gcp_logging\n\n\nsetup_gcp_logging('my-logger')\n\nprint('This is a test message')\n\nraise Exception('This is a test exception')\n```\n\n\u26a0 **Important**: This method will NOT work in case of any submodules that initialize their own logger. In that case, you should use the first method instead.\n\n## Authentication\n\nAs the package exports logs on GCP Logging, you need some GCP credentials. You can provide them in the following ways:\n\n1. By setting either one of the following environment variables:\n - `GOOGLE_APPLICATION_CREDENTIALS`: the path to the local GCP credentials file, or\n - `GCP_CREDENTIALS_JSON`: a string containing the GCP credentials JSON\n2. By passing the one of the following parameters to the `GCPLoggingHandler` class:\n - `gcp_credentials_path`: the path to the local GCP credentials file, or\n - `gcp_credentials_json`: a string containing the GCP credentials JSON\n\n## Examples\n\nFor more examples, see the [examples](./examples) folder.\n\n## Additional Information\n\n### Multiple Handlers\n\n**Please note**: by default, gcp-lolo will NOT print anything to the console. If you want to print logs to the stdout as well, you can add another handler to the logger.\n\nThe following is an example of a `logging.ini` file that uses two different handlers:\n\n```ini\n[loggers]\nkeys=root\n\n[handlers]\nkeys=gcp_handler,console_handler\n\n[formatters]\nkeys=stdOutMessageFormatter\n\n[logger_root]\nlevel=INFO\nhandlers=gcp_handler,console_handler\n\n[handler_gcp_handler]\nclass=gcp_lolo.GCPLoggingHandler\nlevel=INFO\nkwargs={\"name\": \"my-app-with-multiple-logging-handlers\", \"gcp_credentials_path\": \"./gcp_credentials.json\"}\n\n[handler_console_handler]\nclass=logging.StreamHandler\nlevel=DEBUG\nformatter=stdOutMessageFormatter\n\n[formatter_stdOutMessageFormatter]\nformat=%(asctime)s - %(levelname)s - %(name)s - %(message)s\n```\n\nOf course, this applies to any other logging configuration method you may be using.\n\n### Labeling messages\n\nYou can add labels to your messages by passing a `labels` dictionary to the `kwargs` of the `GCPLoggingHandler` in the `logging.ini` file.\n\nExample (pay attention to the `handler_gcp_handler` kwargs):\n\n```ini\n[loggers]\nkeys=root\n\n[handlers]\nkeys=gcp_handler\n\n[formatters]\nkeys=\n\n[logger_root]\nlevel=INFO\nhandlers=gcp_handler\n\n[handler_gcp_handler]\nclass=gcp_lolo.GCPLoggingHandler\nlevel=DEBUG\nkwargs={\"name\": \"my-test-app\", \"gcp_credentials_path\": \"./gcp_credentials.json\", \"labels\": {\"environment\": \"staging\", \"app_version\": \"1.0.0\"}}\n```\n\n## Reference\n\n- [Google Cloud Logging](https://cloud.google.com/logging)\n- [Google Cloud Logging Python Client](https://cloud.google.com/logging/docs/reference/libraries#client-libraries-install-python)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for storing application logs in GCP Cloud Logging.",
"version": "2.0.2",
"project_urls": {
"Homepage": "https://github.com/qurami/gcp-lolo"
},
"split_keywords": [
"logging",
" gcp",
" cloud logging"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8f7b80e251258ad5cd797df17b814ea860eaf6c6e9bbb1826f7b3be1f25c15f0",
"md5": "a2d288a236ff46d28773b0400d2cd781",
"sha256": "d2adb0c92d1eaeb781d684a5f3d33e0877d39810ffbfc426d615d96494b3f257"
},
"downloads": -1,
"filename": "gcp_lolo-2.0.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a2d288a236ff46d28773b0400d2cd781",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6071,
"upload_time": "2025-03-31T11:08:10",
"upload_time_iso_8601": "2025-03-31T11:08:10.116672Z",
"url": "https://files.pythonhosted.org/packages/8f/7b/80e251258ad5cd797df17b814ea860eaf6c6e9bbb1826f7b3be1f25c15f0/gcp_lolo-2.0.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "718ac17537c827528e2a037d9c94a3c056f0252f7317f3d27c5fb646f0dd53e6",
"md5": "82b79d71d8ff925d33239e096f03eac6",
"sha256": "44eb8ddd5899f3a3a28ea55967d8ea53c128de00eba9f78181e4988662a9f7ed"
},
"downloads": -1,
"filename": "gcp_lolo-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "82b79d71d8ff925d33239e096f03eac6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5859,
"upload_time": "2025-03-31T11:08:11",
"upload_time_iso_8601": "2025-03-31T11:08:11.053018Z",
"url": "https://files.pythonhosted.org/packages/71/8a/c17537c827528e2a037d9c94a3c056f0252f7317f3d27c5fb646f0dd53e6/gcp_lolo-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-31 11:08:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "qurami",
"github_project": "gcp-lolo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "google-api-core",
"specs": [
[
"==",
"2.24.2"
]
]
},
{
"name": "google-auth",
"specs": [
[
"==",
"2.38.0"
]
]
},
{
"name": "google-cloud-core",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "google-cloud-logging",
"specs": [
[
">=",
"3.0.0"
]
]
}
],
"lcname": "gcp-lolo"
}
JSON
