Registry / observability / opensearch-logger

opensearch-logger

JSON →
library1.3.1pypypi✓ verified 85d ago

The `opensearch-logger` library provides a logging handler for Python's standard `logging` module, allowing applications to easily send logs to an OpenSearch cluster. It leverages the `opensearch-py` client for reliable communication. Currently at version 1.3.1, it primarily focuses on bug fixes and minor enhancements within its 1.x release cycle, maintaining compatibility.

pip install opensearch-logger
INSTALL
IMPORT
SIG · OPENSEARCH-LOGGER
O
opensearch-logger
observabilitypythonv1.3.1
Install
3.6s avg
Import
987ms
Disk
43MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 1.036s · 49.6MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.6s · import 0.937s · 47MB
43MB installed
● package 43MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OpenSearchHandler
from opensearch_logger import OpenSearchHandler

This quickstart configures a Python logger to send INFO, WARNING, and ERROR messages to an OpenSearch instance. It demonstrates how to initialize the `OpenSearchHandler` with connection details, including host, port, and basic authentication using environment variables for sensitive data, and adds it to a standard Python logger.

import logging import os from opensearch_logger import OpenSearchHandler # Configure logging logger = logging.getLogger("my_app") logger.setLevel(logging.INFO) # OpenSearch connection details (use environment variables for production) host = os.environ.get('OPENSEARCH_HOST', 'localhost') port = int(os.environ.get('OPENSEARCH_PORT', 9200)) username = os.environ.get('OPENSEARCH_USERNAME', 'admin') # Default user for OpenSearch/Dashboards password = os.environ.get('OPENSEARCH_PASSWORD', 'admin') # Default pass for OpenSearch/Dashboards # Handler configuration try: handler = OpenSearchHandler( host=[{'host': host, 'port': port}], http_auth=(username, password), # Required for authenticated clusters use_ssl=True, # Recommended for production; set to False for local http verify_certs=True, # Recommended; set to False for self-signed certs in dev # ssl_assert_hostname=False, # Often needed for dev/test with IP/localhost # ssl_show_warn=False, # Suppress SSL warnings if verify_certs=False index_name='python-app-logs', # Custom index name # auto_create_index=True # Default is True, handler creates index if it doesn't exist ) # Add the handler to the logger logger.addHandler(handler) # Log some messages logger.info("This is an informational message from my application.") logger.warning("A warning occurred: something unexpected happened.") try: 1 / 0 except ZeroDivisionError: logger.exception("An error occurred during division.") print(f"Logs sent to OpenSearch at {host}:{port}") print("Check your OpenSearch instance for 'python-app-logs' index.") except Exception as e: print(f"Failed to configure OpenSearch logger: {e}") print("Ensure OpenSearch is running and accessible with correct credentials/settings.")
Debug
Known issues
gotchaOpenSearch clusters often require `http_auth` credentials and TLS (`use_ssl=True`). Misconfiguring these or omitting them will lead to connection failures or `AuthenticationException`.
fix
Ensure `http_auth` is correctly set with a valid username/password tuple. For TLS, set `use_ssl=True` and configure `verify_certs` and `ssl_assert_hostname` according to your cluster's certificate setup. Use environment variables for credentials.
affects: 1.0.0 - latest
gotchaThe OpenSearch user configured for `http_auth` must have appropriate permissions (e.g., `create_index`, `write`) for the specified `index_name`. If `auto_create_index` is `False`, the index must pre-exist.
fix
Verify that the user has the necessary permissions. If `auto_create_index` is `False`, manually create the index before starting the application, or set `auto_create_index=True` (default behavior).
affects: 1.0.0 - latest
gotchaThe `opensearch-logger` library requires Python 3.9 or newer. Attempting to install or run on older Python versions (e.g., 3.8) will result in installation errors or runtime failures.
fix
Upgrade your Python environment to 3.9 or a newer version. If using a virtual environment, ensure it's created with a compatible Python interpreter.
affects: 1.0.0 - latest
Errors
Common errors & fixes
ConnectionError: Connection refused
The OpenSearch host is not running, is inaccessible, or the host/port configured in the handler is incorrect.
fix
Verify that your OpenSearch cluster is running and reachable from your application's network. Double-check the `host` and `port` settings in `OpenSearchHandler`.
opensearch.exceptions.AuthenticationException: AuthorizationException(401, 'Unauthorized')
Incorrect or missing `http_auth` credentials when connecting to an authenticated OpenSearch cluster.
fix
Provide correct `http_auth` as a `(username, password)` tuple to `OpenSearchHandler`. Ensure the user has the necessary permissions.
opensearch.exceptions.RequestError: RequestError(403, 'Forbidden', 'no permissions for [indices:data/write/index]')
The user configured for `http_auth` lacks permissions to write to the specified index, or `auto_create_index` is `False` and the index does not exist.
fix
Grant the necessary `write` and `create_index` permissions to the OpenSearch user role. Alternatively, ensure the index exists if `auto_create_index=False`.
ERROR: Package 'opensearch-logger' requires Python '>=3.9' but the running Python is 3.8.x
Attempting to install or run the library on an unsupported Python version.
fix
Upgrade your Python environment to version 3.9 or newer using `pyenv`, `conda`, or your system's package manager.
Upgrade
Version history
1.3.1latest on PyPI · released Aug 13, 2025
Audit
Dependencies
opensearch-pyrequiredCore client library used for connecting and sending data to OpenSearch.
Agent activity
14 hits · last 30 days
node
12
OpenAI (training)
2
Resources
opensearch-logger — pip install opensearch-logger · libregistry