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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.036s · 49.6MB
glibcpy 3.10–3.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.")
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.
fixVerify 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.
fixProvide 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.
fixGrant 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.
fixUpgrade 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.