gen3logging 2.0.0__tar.gz

gen3logging-2.0.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

gen3logging-2.0.0/NOTICE

@@ -0,0 +1,7 @@
+Copyright 2017 University of Chicago
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.    You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

gen3logging-2.0.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: gen3logging
+Version: 2.0.0
+Summary: Standardized logging tool and format for Gen3
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Author: CTDS UChicago
+Author-email: cdis@uchicago.edu
+Requires-Python: >=3.13,<4
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Logging
+Project-URL: Homepage, https://github.com/uc-cdis/gen3logging
+Project-URL: Repository, https://github.com/uc-cdis/gen3logging
+Description-Content-Type: text/markdown
+
+# gen3logging
+
+Logging routines to centralize format.
+
+## Basic usage
+
+---
+
+In the parent/root module:
+
+```python
+from gen3logging import get_logger
+
+logger = get_logger("{{service_name}}", log_level='info')
+logger.info('Hello world!')
+```
+
+In a child module:
+
+```python
+from gen3logging import get_logger
+
+logger = get_logger(__name__)
+logger.info('Hello world!')
+
+logger = get_logger(__name__, log_level='debug')
+logger.debug('I am a child logger but I now have my own custom log level!')
+```
+
+You _must_ set the logging level on the parent logger!
+
+Inheritance is by dotted name, so the root logger's name must be a prefix of the
+child module's `__name__`. Naming the root after the top-level package (a module
+in `fence/auth.py` has `__name__ == "fence.auth"`, which inherits from `fence`)
+is what makes this work. A root name that is not a prefix of its modules' names
+gets no children.
+
+The default `log_level` argument in `get_logger` is `None`, which means the default logging level for new loggers is `NOTSET`. This means that child loggers whose levels were not explicitly set will inherit logging levels and handlers from ancestor loggers. This makes it easier to do things like change application-wide logging levels by just setting the level on the parent logger. Levels and handlers can still be individually set on child nodes by providing a `log_level` argument.
+
+See more about Python logging [here](https://docs.python.org/3/library/logging.html).
+
+## Parameters
+
+---
+
+`get_logger` takes:
+
+* `logger_name` - name of the logger, or `None` for the root logger
+* `file_name` (default: `None`) - if present, the logger will output logs to a file as well as stdout
+* `log_level` (default: `None`) - one of `notset`, `debug`, `info`, `warning`, `warn`, `error`, `critical`, in any case. Anything else raises `ValueError`
+* `format` (default: `None`, meaning the format below) - `%`-style format string for text output
+* `json_logs` (default: `None`, meaning the `GEN3_JSON_LOGS` env var decides) - emit JSON instead of text
+
+`file_name`, `format` and `json_logs` only apply when a logger first gets its
+handlers, on the first call that sets a level other than `notset`. Calling
+`get_logger` again for the same logger keeps its existing handlers, so set
+`GEN3_JSON_LOGS` to switch a whole service to JSON regardless of call order.
+
+## Output format
+
+---
+
+By default logs are plain text:
+
+```
+[2025-01-15 12:22:04,031][      fence][   INFO] user logged in
+```
+
+When OpenTelemetry is active, trace context is appended automatically:
+
+```
+[2025-01-15 12:22:04,031][      fence][   INFO] user logged in [trace_id=4bf92f3577b34da6a3ce929d0e0e4736 span_id=00f067aa0ba902b7 service=fence]
+```
+
+The suffix carries only the fields that are available, and is absent entirely
+when none are. It follows the message, ahead of any traceback or stack.
+`gen3logging` does not depend on OpenTelemetry: populate these by
+installing `opentelemetry-instrumentation-logging` and calling
+`LoggingInstrumentor().instrument()`. Nothing needs to change here to pick them
+up, and nothing fails when they are missing.
+
+`trace_id` and `span_id` are either a usable id or absent.
+
+Any `%`-style format string can replace the default:
+
+```python
+logger = get_logger("gen3foo", log_level='info', format="%(levelname)s %(message)s")
+```
+
+## Enabling JSON Logs
+
+---
+
+Set `json_logs=True` to emit one JSON object per line instead of the default format:
+
+```python
+logger = get_logger("gen3foo", log_level='info', json_logs=True)
+```
+
+```json
+{"timestamp": "2025-01-15T18:22:04.031Z", "logger": "fence.auth", "level": "INFO", "message": "user logged in", "trace_id": null, "span_id": null, "service": null}
+```
+
+| Key                              | Value                                                             |
+| -------------------------------- | ----------------------------------------------------------------- |
+| `timestamp`                      | ISO 8601 UTC, millisecond precision                               |
+| `logger`                         | logger name                                                       |
+| `level`                          | level name, e.g. `INFO`                                           |
+| `message`                        | the formatted message, with `%`-style arguments interpolated      |
+| `trace_id`, `span_id`, `service` | OpenTelemetry correlation, `null` when unavailable                |
+| `exception`                      | traceback text, present only on records that carry exception info |
+| `stack_info`                     | stack text, present only on records logged with `stack_info=True` |
+
+Fields passed through a logging call's `extra=` are not included.
+
+Because the message and traceback are JSON-escaped, a multi-line traceback stays
+on a single log line and can be parsed by a log aggregator without stitching.
+
+To turn JSON on for a deployment without a code change, set the
+`GEN3_JSON_LOGS` environment variable:
+
+```
+GEN3_JSON_LOGS=true
+```
+
+An explicit `json_logs` argument always wins over the environment variable, so a
+service can force either format. When `json_logs` is omitted the environment
+variable decides, and when neither is set, output is text. Enabling JSON
+supersedes any `format` string.
+
+## Migrating from `cdislogging`
+
+---
+
+1. Replace the `cdislogging` dependency with `gen3logging>=2.0.0`.
+2. Replace `from cdislogging import ...` with `from gen3logging import ...`.
+
+That is the whole migration. Output is identical to `cdislogging` 1.2.0
+until you enable JSON or instrument with OpenTelemetry.
+
+> NOTE: The library also now contains a PEP 561 py.typed marker, which tells type checkers to enforce our typing.
+

gen3logging-2.0.0/README.md

@@ -0,0 +1,141 @@
+# gen3logging
+
+Logging routines to centralize format.
+
+## Basic usage
+
+---
+
+In the parent/root module:
+
+```python
+from gen3logging import get_logger
+
+logger = get_logger("{{service_name}}", log_level='info')
+logger.info('Hello world!')
+```
+
+In a child module:
+
+```python
+from gen3logging import get_logger
+
+logger = get_logger(__name__)
+logger.info('Hello world!')
+
+logger = get_logger(__name__, log_level='debug')
+logger.debug('I am a child logger but I now have my own custom log level!')
+```
+
+You _must_ set the logging level on the parent logger!
+
+Inheritance is by dotted name, so the root logger's name must be a prefix of the
+child module's `__name__`. Naming the root after the top-level package (a module
+in `fence/auth.py` has `__name__ == "fence.auth"`, which inherits from `fence`)
+is what makes this work. A root name that is not a prefix of its modules' names
+gets no children.
+
+The default `log_level` argument in `get_logger` is `None`, which means the default logging level for new loggers is `NOTSET`. This means that child loggers whose levels were not explicitly set will inherit logging levels and handlers from ancestor loggers. This makes it easier to do things like change application-wide logging levels by just setting the level on the parent logger. Levels and handlers can still be individually set on child nodes by providing a `log_level` argument.
+
+See more about Python logging [here](https://docs.python.org/3/library/logging.html).
+
+## Parameters
+
+---
+
+`get_logger` takes:
+
+* `logger_name` - name of the logger, or `None` for the root logger
+* `file_name` (default: `None`) - if present, the logger will output logs to a file as well as stdout
+* `log_level` (default: `None`) - one of `notset`, `debug`, `info`, `warning`, `warn`, `error`, `critical`, in any case. Anything else raises `ValueError`
+* `format` (default: `None`, meaning the format below) - `%`-style format string for text output
+* `json_logs` (default: `None`, meaning the `GEN3_JSON_LOGS` env var decides) - emit JSON instead of text
+
+`file_name`, `format` and `json_logs` only apply when a logger first gets its
+handlers, on the first call that sets a level other than `notset`. Calling
+`get_logger` again for the same logger keeps its existing handlers, so set
+`GEN3_JSON_LOGS` to switch a whole service to JSON regardless of call order.
+
+## Output format
+
+---
+
+By default logs are plain text:
+
+```
+[2025-01-15 12:22:04,031][      fence][   INFO] user logged in
+```
+
+When OpenTelemetry is active, trace context is appended automatically:
+
+```
+[2025-01-15 12:22:04,031][      fence][   INFO] user logged in [trace_id=4bf92f3577b34da6a3ce929d0e0e4736 span_id=00f067aa0ba902b7 service=fence]
+```
+
+The suffix carries only the fields that are available, and is absent entirely
+when none are. It follows the message, ahead of any traceback or stack.
+`gen3logging` does not depend on OpenTelemetry: populate these by
+installing `opentelemetry-instrumentation-logging` and calling
+`LoggingInstrumentor().instrument()`. Nothing needs to change here to pick them
+up, and nothing fails when they are missing.
+
+`trace_id` and `span_id` are either a usable id or absent.
+
+Any `%`-style format string can replace the default:
+
+```python
+logger = get_logger("gen3foo", log_level='info', format="%(levelname)s %(message)s")
+```
+
+## Enabling JSON Logs
+
+---
+
+Set `json_logs=True` to emit one JSON object per line instead of the default format:
+
+```python
+logger = get_logger("gen3foo", log_level='info', json_logs=True)
+```
+
+```json
+{"timestamp": "2025-01-15T18:22:04.031Z", "logger": "fence.auth", "level": "INFO", "message": "user logged in", "trace_id": null, "span_id": null, "service": null}
+```
+
+| Key                              | Value                                                             |
+| -------------------------------- | ----------------------------------------------------------------- |
+| `timestamp`                      | ISO 8601 UTC, millisecond precision                               |
+| `logger`                         | logger name                                                       |
+| `level`                          | level name, e.g. `INFO`                                           |
+| `message`                        | the formatted message, with `%`-style arguments interpolated      |
+| `trace_id`, `span_id`, `service` | OpenTelemetry correlation, `null` when unavailable                |
+| `exception`                      | traceback text, present only on records that carry exception info |
+| `stack_info`                     | stack text, present only on records logged with `stack_info=True` |
+
+Fields passed through a logging call's `extra=` are not included.
+
+Because the message and traceback are JSON-escaped, a multi-line traceback stays
+on a single log line and can be parsed by a log aggregator without stitching.
+
+To turn JSON on for a deployment without a code change, set the
+`GEN3_JSON_LOGS` environment variable:
+
+```
+GEN3_JSON_LOGS=true
+```
+
+An explicit `json_logs` argument always wins over the environment variable, so a
+service can force either format. When `json_logs` is omitted the environment
+variable decides, and when neither is set, output is text. Enabling JSON
+supersedes any `format` string.
+
+## Migrating from `cdislogging`
+
+---
+
+1. Replace the `cdislogging` dependency with `gen3logging>=2.0.0`.
+2. Replace `from cdislogging import ...` with `from gen3logging import ...`.
+
+That is the whole migration. Output is identical to `cdislogging` 1.2.0
+until you enable JSON or instrument with OpenTelemetry.
+
+> NOTE: The library also now contains a PEP 561 py.typed marker, which tells type checkers to enforce our typing.

gen3logging-2.0.0/gen3logging/__init__.py

@@ -0,0 +1,360 @@
+"""
+Logging with a standardized format
+"""
+
+import json
+import logging
+import os
+import sys
+import time
+from types import MappingProxyType
+from typing import TextIO
+
+FORMAT = "[%(asctime)s][%(name)10s][%(levelname)7s] %(message)s"
+
+JSON_LOGS_ENV_VAR = "GEN3_JSON_LOGS"
+
+_TRUTHY = frozenset({"1", "true", "t", "yes", "y", "on"})
+
+_LOG_LEVELS = MappingProxyType(
+    {
+        "notset": logging.NOTSET,
+        "debug": logging.DEBUG,
+        "info": logging.INFO,
+        "warning": logging.WARNING,
+        "warn": logging.WARNING,
+        "error": logging.ERROR,
+        "critical": logging.CRITICAL,
+    }
+)
+
+_TRACE_SUFFIX_ATTRIBUTE = "gen3_trace_suffix"
+
+_OTEL_ATTRIBUTES = (
+    ("trace_id", "otelTraceID"),
+    ("span_id", "otelSpanID"),
+    ("service", "otelServiceName"),
+)
+
+
+class TextFormatter(logging.Formatter):
+    """
+    Format records with a %-style template, appending trace context.
+
+    The trace suffix is appended only when OpenTelemetry supplied usable
+    correlation ids, so output is unchanged from a plain logging.Formatter
+    whenever no trace is recording.
+    """
+
+    def __init__(self, fmt: str, datefmt: str | None = None) -> None:
+        """
+        Build a formatter whose template ends with the trace suffix.
+
+        The suffix must stay a template field: format appends any traceback
+        and stack after the template, so this is what keeps the suffix on the
+        message line.
+
+        Args:
+            fmt (str): %-style format string.
+            datefmt (str | None): strftime format for asctime, or None for the
+                                     logging default.
+        """
+
+        super().__init__(fmt + "%(" + _TRACE_SUFFIX_ATTRIBUTE + ")s", datefmt)
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        Render a record as text, with a trace suffix when one is available.
+
+        Args:
+            record (logging.LogRecord): record to format.
+
+        Returns:
+            str: the formatted line, followed by any traceback or stack.
+        """
+
+        setattr(record, _TRACE_SUFFIX_ATTRIBUTE, _trace_suffix(record))
+
+        return super().format(record)
+
+
+class JsonFormatter(logging.Formatter):
+    """
+    Format log records as single-line JSON objects.
+
+    OpenTelemetry correlation fields are read off the record when present and
+    emitted as null otherwise, so records format correctly whether or not
+    opentelemetry-instrumentation-logging is installed and instrumenting.
+
+    Fields passed through a logging call's `extra=` are not emitted.
+    """
+
+    # gmtime pairs with the trailing Z in default_msec_format; localtime would
+    # label local times as UTC. staticmethod is for type checkers, which treat a
+    # bare callable class attribute as an unbound method and reject it as an
+    # incompatible override of Formatter.converter.
+    converter = staticmethod(time.gmtime)
+    default_time_format = "%Y-%m-%dT%H:%M:%S"
+    default_msec_format = "%s.%03dZ"
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        Render a record as a JSON object.
+
+        Args:
+            record (logging.LogRecord): record to format.
+
+        Returns:
+            str: single-line JSON object.
+        """
+
+        payload = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "logger": record.name,
+            "level": record.levelname,
+            "message": record.getMessage(),
+            **_otel_fields(record),
+        }
+
+        if record.exc_info:
+            payload["exception"] = self.formatException(record.exc_info)
+        if record.stack_info:
+            payload["stack_info"] = self.formatStack(record.stack_info)
+
+        # default=str keeps a non-serializable value from raising inside a log call
+        return json.dumps(payload, default=str)
+
+
+def get_stream_handler(
+    format: str | None = None, json_logs: bool | None = None
+) -> logging.StreamHandler[TextIO]:
+    """
+    Return a stdout stream handler
+
+    All logs will write to stdout.
+
+    Args:
+        format (str | None): %-style format string. Defaults to
+                                FORMAT. Ignored when JSON is enabled.
+        json_logs (bool | None): emit JSON instead of text. When None, falls
+                                    back to the GEN3_JSON_LOGS env var.
+
+    Returns:
+        logging.StreamHandler[TextIO]: pre-formatted stream handler
+    """
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(_get_formatter(format, json_logs))
+
+    return handler
+
+
+def get_file_handler(
+    file_name: str, format: str | None = None, json_logs: bool | None = None
+) -> logging.FileHandler:
+    """
+    Return a file handler
+
+    Args:
+        file_name (str): name of file to write logs to
+        format (str | None): %-style format string. Defaults to
+                                FORMAT. Ignored when JSON is enabled.
+        json_logs (bool | None): emit JSON instead of text. When None, falls
+                                    back to the GEN3_JSON_LOGS env var.
+
+    Returns:
+        logging.FileHandler: pre-formatted file handler
+    """
+
+    handler = logging.FileHandler(file_name)
+    handler.setFormatter(_get_formatter(format, json_logs))
+
+    return handler
+
+
+def get_logger(
+    logger_name: str | None,
+    file_name: str | None = None,
+    log_level: str | None = None,
+    format: str | None = None,
+    json_logs: bool | None = None,
+) -> logging.Logger:
+    """
+    Return an opinionated basic logger named `logger_name` that logs to stdout
+
+    If you leave the log level argument as None and the logger was not
+    previously instantiated, the level will be set to NOTSET. If the logger
+    was previously instantiated, the level will be left alone.
+
+    If the level is NOTSET, then ancestor loggers are traversed and searched
+    for a log_level and handler. See python docs.
+
+    If you change the log level to something other than debug (or notset) then it will not
+    display log statements below that level (see example below for details).
+    Ideally this should be handled by your application's command line args.
+
+    file_name, format and json_logs only apply when the logger gets its
+    handlers, which happens on the first call that sets a level other than
+    notset. A later call for the same logger leaves its handlers as they are,
+    so GEN3_JSON_LOGS is the reliable way to switch a whole service to JSON.
+
+    eg:
+    ```
+    log = get_logger('hi', log_level='info')
+    log.debug('hello world') # <- this will not display
+    ```
+
+    Args:
+        logger_name (str | None): name of the logger, or None for the root logger.
+                                     Python's root logger defaults to WARNING, so it
+                                     gets a handler even without a log_level, and
+                                     log_level="notset" removes every root handler,
+                                     including ones other libraries installed.
+        file_name (str | None): if present, will write logs to file as well
+        log_level (str | None): level of logging for this logger, in any case. string
+                                   so you don't have to import logging in the
+                                   application
+        format (str | None): %-style format string. Defaults to
+                                FORMAT. Ignored when JSON is enabled.
+        json_logs (bool | None): emit JSON instead of text. When None, falls
+                                    back to the GEN3_JSON_LOGS env var.
+
+    Returns:
+        logging.Logger: pre-formatted logger object
+
+    Raises:
+        ValueError: if log_level is not one of the supported level names.
+    """
+
+    logger = logging.getLogger(logger_name)
+
+    if log_level:
+        # notset maps to 0, so a falsiness check would reject it
+        level = (
+            _LOG_LEVELS.get(log_level.lower()) if isinstance(log_level, str) else None
+        )
+        if level is None:
+            raise ValueError(
+                f"Invalid log_level parameter: {log_level}. "
+                f"Expected one of these strings (case-insensitive): {', '.join(_LOG_LEVELS)}"
+                f"(e.g. log_level='info' instead of logging.INFO)."
+            )
+
+        logger.setLevel(level)
+    # Else, NOTSET is Python default.
+
+    logger.propagate = logger.level == logging.NOTSET
+
+    if logger.level != logging.NOTSET and not logger.handlers:
+        logger.addHandler(get_stream_handler(format=format, json_logs=json_logs))
+
+        if file_name:
+            logger.addHandler(
+                get_file_handler(file_name, format=format, json_logs=json_logs)
+            )
+    # Else if at least one log handler exists that means it has been
+    # instantiated with the same name before. Do not keep creating handlers
+    # or your logs will be very messy.
+    if logger.level == logging.NOTSET:
+        # Delete handlers in case level was set back to NOTSET
+        # after being set to something else
+        del logger.handlers[:]
+
+    return logger
+
+
+def _get_formatter(format: str | None, json_logs: bool | None) -> logging.Formatter:
+    """
+    Return the formatter for a format and JSON selection.
+
+    Args:
+        format (str | None): %-style format string, or None for FORMAT.
+        json_logs (bool | None): whether to emit JSON. None defers to the
+                                    GEN3_JSON_LOGS env var.
+
+    Returns:
+        logging.Formatter: JsonFormatter when JSON is enabled, otherwise a
+            TextFormatter over the given template.
+    """
+
+    if json_logs is None:
+        json_logs = _json_logs_enabled_in_env()
+
+    if json_logs:
+        return JsonFormatter()
+
+    return TextFormatter(format or FORMAT)
+
+
+def _json_logs_enabled_in_env() -> bool:
+    """
+    Return whether the GEN3_JSON_LOGS env var asks for JSON output.
+
+    Returns:
+        bool: True when the env var holds a recognized truthy value.
+    """
+
+    return os.environ.get(JSON_LOGS_ENV_VAR, "").strip().lower() in _TRUTHY
+
+
+def _trace_suffix(record: logging.LogRecord) -> str:
+    """
+    Build the bracketed trace suffix for a text log line.
+
+    Args:
+        record (logging.LogRecord): record to read correlation fields from.
+
+    Returns:
+        str: suffix beginning with a space, or an empty string when no trace
+            context is available.
+    """
+
+    available = [
+        "{}={}".format(label, value)
+        for label, value in _otel_fields(record).items()
+        if value is not None
+    ]
+
+    if not available:
+        return ""
+
+    return " [{}]".format(" ".join(available))
+
+
+def _otel_fields(record: logging.LogRecord) -> dict[str, str | None]:
+    """
+    Read OpenTelemetry correlation fields off a record.
+
+    Args:
+        record (logging.LogRecord): record to read from.
+
+    Returns:
+        dict[str, str | None]: correlation field names mapped to their value,
+            or None when the field is unavailable.
+    """
+
+    return {
+        label: _otel_value(record, attribute) for label, attribute in _OTEL_ATTRIBUTES
+    }
+
+
+def _otel_value(record: logging.LogRecord, attribute: str) -> str | None:
+    """
+    Read one OpenTelemetry attribute, normalizing "no trace" to None.
+
+    Args:
+        record (logging.LogRecord): record to read the value from.
+        attribute (str): name of the record attribute holding the value.
+
+    Returns:
+        str | None: the value, or None when no trace was recording.
+    """
+
+    value = getattr(record, attribute, None)
+
+    # LoggingInstrumentor writes "0" for ids when no span is recording, and an
+    # empty service name when unset.
+    if not value or (isinstance(value, str) and not value.strip("0")):
+        return None
+
+    return value

gen3logging-2.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "gen3logging"
+version = "2.0.0"
+description = "Standardized logging tool and format for Gen3"
+authors = [{ name = "CTDS UChicago", email = "cdis@uchicago.edu" }]
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+readme = "README.md"
+requires-python = ">=3.13,<4"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Logging",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/uc-cdis/gen3logging"
+Repository = "https://github.com/uc-cdis/gen3logging"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "*"
+deptry = "*"
+ty = "*"
+
+[build-system]
+requires = ["poetry-core>=2.0"]
+build-backend = "poetry.core.masonry.api"