# Mercurial logs through the `logging` module
This extension redirects most user feedback meant for terminals to the
Python `logging` module of the standard library.
This is intended intended primarily for server-side use cases, and is unlikely
to be useful for client-side operation.
Indeed on a server, many messages are useful for the systems administrator
only, and would be unwanted pollution if seen by the client.
A notable exception is `ui.status` which is really used
to report back meaningful information over the wire.
Using logging is more robust and flexible than using flags such as
`ui.debug` and redirecting `stderr`. It also provides integration with
Sentry (see below). Many other logs aggregation systems that have a `logging`
handler could be directly used.
At the time of this writing, it has the side effect to disable other extensions
meant for logs, such as `blackbox`.
## Installation
Install with `pip` or `pip3`:
```
pip install hgext-loggingmod
pip3 install "hgext-loggingmod>=0.2.0"
```
Then, in your HGRC, include this:
```ini
[extensions]
loggingmod =
```
## Configuration
All parameters are to be set within the `[logging]` hgrc section.
### Basic configuration
These are applied first, using mostly
[`logging.basicConfig`](https://docs.python.org/library/logging.html?highlight=basicconfig#logging.basicConfig)
Example (these are the default values):
```ini
[logging]
level = info
format = [%(asctime)s] [%(process)d] [%(levelname)s] [%(name)s] %(message)s
hg_format = [%(asctime)s] [%(process)d] repo:%(repo)s [%(levelname)s] [%(name)s] %(message)s
```
#### Logging to a file
```ini
[logging]
file = /var/log/mercurial.log
```
#### Format
The `format` string is a regular logging format string, see
[LogRecord attributes](https://docs.python.org/library/logging.html#logrecord-attributes) for a full list of the keys that can be used there.
The `hg_format` string is also a regular logging format string, but it
can additionally make use of the **`repo` parameter**: the full path to the
current repository on the file system, if relevant to the given log record.
This format is used in the `hg` logger and its descendants, such as
`hg.logging`, `hg.discovery` etc.
The times will include the timezone by default.
### Advanced configuration through files
#### JSON
This is the most complete, as it leverages [`dictConfig()`](https://docs.python.org/library/logging.config.html#logging.config.dictConfig)
```
[logging]
config.json = /etc/hg-logging.json
```
The basic configuration above is done first nevertheless, but it is wiped out
unless one uses the `incremental` keyword.
### INI
This is forwarded to [`fileConfig()`](https://docs.python.org/3/library/logging.config.html#logging.config.fileConfig)
```
[logging]
config.ini = /etc/hg-logging.ini
```
## Using with Sentry
### Prerequisites
The `sentry_sdk` package should be importable from the Mercurial process, see
[Sentry install instructions](https://docs.sentry.io/platforms/python/#integrating-the-sdk)
In our experience, `pip install sentry-sdk` has not been enough, we had to also
install [Brotli](https://pypi.org/project/Brotli/) as well. Your mileage may
vary.
In doubt, [test it first](https://docs.sentry.io/platforms/python/#verifying-your-setup)
### Activation
To forward logs to Sentry, just specify the DSN in the hgrc:
```[ini]
[logging]
sentry.dsn = https://<key>@sentry.example.net/<project>
```
Warning : don't use quotes above.
### Basic configuration
The Sentry default integration catches all logging calls, and is orthogonal
to the regular `logging` configuration, except for the logger levels.
This extension has several knobs to tweak it.
Here's an example
```ini
[logging]
sentry.ignore_loggers = discovery extension
# these are the default values:
sentry.event_level = error
sentry.breadcrumb_level = info
```
### Fine configuration
Instead of the flat configuration as above, you can disable the blanket
integration and resort to explicit configuration with the `config.json`
directive and Sentry's handlers
```ini
[logging]
config.json = /etc/hg-config-with-sentry.conf
sentry.dsn = https://<key>@sentry.example.net/<project>
sentry.default_integration = false
```
Of course, this also disables the `sentry.event_level` and
`sentry.breadcrumbs_level` config items.
At the time of this writing, these handlers are
- `sentry_sdk.integrations.logging.EventHandler`
- `sentry_sdk.integrations.logging.BreadCrumbHandler`
See also: [Handler classes](https://docs.sentry.io/platforms/python/logging/#handler-classes) in Sentry documentation
Raw data
{
"_id": null,
"home_page": "https://dev.heptapod.net/heptapod/hgext-loggingmod",
"name": "hg-loggingmod",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "hg mercurial",
"author": "Georges Racinet",
"author_email": "georges.racinet@octobus.net",
"download_url": "https://files.pythonhosted.org/packages/f1/8f/bb4487b2a0d9040f81e3d23602098bf7a5bbe55a0f637261f3d0114ec586/hg-loggingmod-0.4.1.tar.gz",
"platform": null,
"description": "# Mercurial logs through the `logging` module\n\nThis extension redirects most user feedback meant for terminals to the\nPython `logging` module of the standard library.\n\nThis is intended intended primarily for server-side use cases, and is unlikely\nto be useful for client-side operation.\n\nIndeed on a server, many messages are useful for the systems administrator\nonly, and would be unwanted pollution if seen by the client.\nA notable exception is `ui.status` which is really used\nto report back meaningful information over the wire.\n\nUsing logging is more robust and flexible than using flags such as\n`ui.debug` and redirecting `stderr`. It also provides integration with\nSentry (see below). Many other logs aggregation systems that have a `logging`\nhandler could be directly used.\n\nAt the time of this writing, it has the side effect to disable other extensions\nmeant for logs, such as `blackbox`.\n\n## Installation\n\nInstall with `pip` or `pip3`:\n\n```\n pip install hgext-loggingmod\n pip3 install \"hgext-loggingmod>=0.2.0\"\n```\n\nThen, in your HGRC, include this:\n\n```ini\n[extensions]\nloggingmod =\n```\n\n## Configuration\n\nAll parameters are to be set within the `[logging]` hgrc section.\n\n### Basic configuration\n\nThese are applied first, using mostly\n[`logging.basicConfig`](https://docs.python.org/library/logging.html?highlight=basicconfig#logging.basicConfig)\n\nExample (these are the default values):\n\n```ini\n[logging]\nlevel = info\nformat = [%(asctime)s] [%(process)d] [%(levelname)s] [%(name)s] %(message)s\nhg_format = [%(asctime)s] [%(process)d] repo:%(repo)s [%(levelname)s] [%(name)s] %(message)s\n```\n\n#### Logging to a file\n\n```ini\n[logging]\nfile = /var/log/mercurial.log\n```\n\n#### Format\n\nThe `format` string is a regular logging format string, see\n[LogRecord attributes](https://docs.python.org/library/logging.html#logrecord-attributes) for a full list of the keys that can be used there.\n\nThe `hg_format` string is also a regular logging format string, but it\ncan additionally make use of the **`repo` parameter**: the full path to the\ncurrent repository on the file system, if relevant to the given log record.\nThis format is used in the `hg` logger and its descendants, such as\n`hg.logging`, `hg.discovery` etc.\n\nThe times will include the timezone by default.\n\n### Advanced configuration through files\n\n#### JSON\n\nThis is the most complete, as it leverages [`dictConfig()`](https://docs.python.org/library/logging.config.html#logging.config.dictConfig)\n\n```\n[logging]\nconfig.json = /etc/hg-logging.json\n```\n\nThe basic configuration above is done first nevertheless, but it is wiped out\nunless one uses the `incremental` keyword.\n\n### INI\n\nThis is forwarded to [`fileConfig()`](https://docs.python.org/3/library/logging.config.html#logging.config.fileConfig)\n\n```\n[logging]\nconfig.ini = /etc/hg-logging.ini\n```\n\n## Using with Sentry\n\n### Prerequisites\n\nThe `sentry_sdk` package should be importable from the Mercurial process, see\n[Sentry install instructions](https://docs.sentry.io/platforms/python/#integrating-the-sdk)\n\nIn our experience, `pip install sentry-sdk` has not been enough, we had to also\ninstall [Brotli](https://pypi.org/project/Brotli/) as well. Your mileage may\nvary.\n\n\nIn doubt, [test it first](https://docs.sentry.io/platforms/python/#verifying-your-setup)\n\n### Activation\n\nTo forward logs to Sentry, just specify the DSN in the hgrc:\n\n```[ini]\n[logging]\nsentry.dsn = https://<key>@sentry.example.net/<project>\n```\n\nWarning : don't use quotes above.\n\n### Basic configuration\n\nThe Sentry default integration catches all logging calls, and is orthogonal\nto the regular `logging` configuration, except for the logger levels.\n\nThis extension has several knobs to tweak it.\nHere's an example\n\n```ini\n[logging]\nsentry.ignore_loggers = discovery extension\n\n# these are the default values:\nsentry.event_level = error\nsentry.breadcrumb_level = info\n```\n\n### Fine configuration\n\nInstead of the flat configuration as above, you can disable the blanket\nintegration and resort to explicit configuration with the `config.json`\ndirective and Sentry's handlers\n\n```ini\n[logging]\nconfig.json = /etc/hg-config-with-sentry.conf\nsentry.dsn = https://<key>@sentry.example.net/<project>\nsentry.default_integration = false\n```\n\nOf course, this also disables the `sentry.event_level` and\n`sentry.breadcrumbs_level` config items.\n\nAt the time of this writing, these handlers are\n\n- `sentry_sdk.integrations.logging.EventHandler`\n- `sentry_sdk.integrations.logging.BreadCrumbHandler`\n\nSee also: [Handler classes](https://docs.sentry.io/platforms/python/logging/#handler-classes) in Sentry documentation\n",
"bugtrack_url": null,
"license": "GPLv2+",
"summary": "Managing Mercurial logs with the standard Python logging module",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://dev.heptapod.net/heptapod/hgext-loggingmod"
},
"split_keywords": [
"hg",
"mercurial"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f18fbb4487b2a0d9040f81e3d23602098bf7a5bbe55a0f637261f3d0114ec586",
"md5": "834fcd0914bac8e36068c29097f4dbc8",
"sha256": "70549f50fc12f9b7a20f0faf43fc1ca3aa5ebb9cbee66a0d7c8a1f9c23d04d29"
},
"downloads": -1,
"filename": "hg-loggingmod-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "834fcd0914bac8e36068c29097f4dbc8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14251,
"upload_time": "2024-06-09T12:49:12",
"upload_time_iso_8601": "2024-06-09T12:49:12.832614Z",
"url": "https://files.pythonhosted.org/packages/f1/8f/bb4487b2a0d9040f81e3d23602098bf7a5bbe55a0f637261f3d0114ec586/hg-loggingmod-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-09 12:49:12",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hg-loggingmod"
}
JSON