{"id":10014,"library":"opensearch-logger","title":"OpenSearch Logger","description":"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.","status":"active","version":"1.3.1","language":"en","source_language":"en","source_url":"https://github.com/opensearch-project/opensearch-py-logger","tags":["logging","opensearch","elasticsearch","log-management","observability"],"install":[{"cmd":"pip install opensearch-logger","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core client library used for connecting and sending data to OpenSearch.","package":"opensearch-py"}],"imports":[{"symbol":"OpenSearchHandler","correct":"from opensearch_logger import OpenSearchHandler"}],"quickstart":{"code":"import logging\nimport os\nfrom opensearch_logger import OpenSearchHandler\n\n# Configure logging\nlogger = logging.getLogger(\"my_app\")\nlogger.setLevel(logging.INFO)\n\n# OpenSearch connection details (use environment variables for production)\nhost = os.environ.get('OPENSEARCH_HOST', 'localhost')\nport = int(os.environ.get('OPENSEARCH_PORT', 9200))\nusername = os.environ.get('OPENSEARCH_USERNAME', 'admin') # Default user for OpenSearch/Dashboards\npassword = os.environ.get('OPENSEARCH_PASSWORD', 'admin') # Default pass for OpenSearch/Dashboards\n\n# Handler configuration\ntry:\n    handler = OpenSearchHandler(\n        host=[{'host': host, 'port': port}],\n        http_auth=(username, password), # Required for authenticated clusters\n        use_ssl=True, # Recommended for production; set to False for local http\n        verify_certs=True, # Recommended; set to False for self-signed certs in dev\n        # ssl_assert_hostname=False, # Often needed for dev/test with IP/localhost\n        # ssl_show_warn=False, # Suppress SSL warnings if verify_certs=False\n        index_name='python-app-logs', # Custom index name\n        # auto_create_index=True # Default is True, handler creates index if it doesn't exist\n    )\n    # Add the handler to the logger\n    logger.addHandler(handler)\n\n    # Log some messages\n    logger.info(\"This is an informational message from my application.\")\n    logger.warning(\"A warning occurred: something unexpected happened.\")\n    try:\n        1 / 0\n    except ZeroDivisionError:\n        logger.exception(\"An error occurred during division.\")\n    \n    print(f\"Logs sent to OpenSearch at {host}:{port}\")\n    print(\"Check your OpenSearch instance for 'python-app-logs' index.\")\n\nexcept Exception as e:\n    print(f\"Failed to configure OpenSearch logger: {e}\")\n    print(\"Ensure OpenSearch is running and accessible with correct credentials/settings.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"OpenSearch clusters often require `http_auth` credentials and TLS (`use_ssl=True`). Misconfiguring these or omitting them will lead to connection failures or `AuthenticationException`.","severity":"gotcha","affected_versions":"1.0.0 - latest"},{"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).","message":"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.","severity":"gotcha","affected_versions":"1.0.0 - latest"},{"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.","message":"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.","severity":"gotcha","affected_versions":"1.0.0 - latest"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify that your OpenSearch cluster is running and reachable from your application's network. Double-check the `host` and `port` settings in `OpenSearchHandler`.","cause":"The OpenSearch host is not running, is inaccessible, or the host/port configured in the handler is incorrect.","error":"ConnectionError: Connection refused"},{"fix":"Provide correct `http_auth` as a `(username, password)` tuple to `OpenSearchHandler`. Ensure the user has the necessary permissions.","cause":"Incorrect or missing `http_auth` credentials when connecting to an authenticated OpenSearch cluster.","error":"opensearch.exceptions.AuthenticationException: AuthorizationException(401, 'Unauthorized')"},{"fix":"Grant the necessary `write` and `create_index` permissions to the OpenSearch user role. Alternatively, ensure the index exists if `auto_create_index=False`.","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.","error":"opensearch.exceptions.RequestError: RequestError(403, 'Forbidden', 'no permissions for [indices:data/write/index]')"},{"fix":"Upgrade your Python environment to version 3.9 or newer using `pyenv`, `conda`, or your system's package manager.","cause":"Attempting to install or run the library on an unsupported Python version.","error":"ERROR: Package 'opensearch-logger' requires Python '>=3.9' but the running Python is 3.8.x"}]}