OpenSearch Logger

Common errors

• ConnectionError: Connection refused

  cause 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')

  cause 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]')

  cause 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

  cause 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.

Warnings

• gotcha OpenSearch 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.
• gotcha The 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).
• gotcha The `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.

Install

• pip install opensearch-logger Install latest version

Imports

• OpenSearchHandler

  from opensearch_logger import OpenSearchHandler

Quickstart

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.")