-
Notifications
You must be signed in to change notification settings - Fork 183
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Loading status checks…
Added a guide & sample for a custom logger client implementation. (#579)
* Added a guide & sample for a custom logger client implementation. Signed-off-by: Djcarrillo6 <[email protected]> Black formatter Signed-off-by: Djcarrillo6 <[email protected]> * Changes from PR review Signed-off-by: Djcarrillo6 <[email protected]> Fixed import formatting in sample code for gudie. Signed-off-by: Djcarrillo6 <[email protected]> Fixed nox formatting of log collection sample module. Signed-off-by: Djcarrillo6 <[email protected]> Added types to log_collection_sample.py Signed-off-by: Djcarrillo6 <[email protected]> Added type ignore to StramHandler class Signed-off-by: Djcarrillo6 <[email protected]> Added formatting change Signed-off-by: Djcarrillo6 <[email protected]> * Added PR review changes. Signed-off-by: Djcarrillo6 <[email protected]> Fixed typo in CHANGELOG. Signed-off-by: Djcarrillo6 <[email protected]> Requested changes. Signed-off-by: Djcarrillo6 <[email protected]> Requested changes again. Signed-off-by: Djcarrillo6 <[email protected]> Added link in USER_GUIDE.md. Signed-off-by: Djcarrillo6 <[email protected]> --------- Signed-off-by: Djcarrillo6 <[email protected]>
1 parent
e92eac2
commit 0cb345d
Showing
4 changed files
with
287 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,169 @@ | ||
- [Log Collection Guide](#log-collection-guide) | ||
- [Import Required Modules](#import-required-modules) | ||
- [Download and Start OpenSearch](#download-and-start-opensearch) | ||
- [Setup Connection with OpenSearch](#setup-connection-with-opensearch) | ||
- [Initialize Logger](#initialize-logger) | ||
- [Custom Handler For Logs](#custom-handler-for-logs) | ||
- [Create OpenSearch Handler and Add to Logger](#create-opensearch-handler-and-add-to-logger) | ||
- [Setup Asynchronous Logging Using Queues](#setup-asynchronous-logging-using-queues) | ||
- [Clean Up](#clean-up) | ||
- [Sample Code](#sample-code) | ||
|
||
|
||
## Log Collection Guide | ||
In this guide, we will look at how to collect logs from your application and send them to OpenSearch. | ||
|
||
## Import Required Modules | ||
Let's import the required modules: | ||
|
||
```python | ||
import logging | ||
import queue | ||
from datetime import datetime | ||
from logging.handlers import QueueHandler, QueueListener | ||
from typing import Any | ||
|
||
import urllib3 | ||
|
||
from opensearchpy import OpenSearch | ||
|
||
urllib3.disable_warnings() | ||
``` | ||
|
||
## Download and Start OpenSearch | ||
``` | ||
docker pull opensearchproject/opensearch:latest | ||
``` | ||
|
||
``` | ||
docker run -d -p 9200:9200 -p 9600:9600 --name opensearch_opensearch_1 -e "discovery.type=single-node" opensearchproject/opensearch:latest | ||
``` | ||
|
||
## Setup Connection with OpenSearch | ||
|
||
Create a client instance: | ||
```python | ||
opensearch_client: Any = OpenSearch( | ||
"https://admin:admin@localhost:9200", | ||
use_ssl=True, | ||
verify_certs=False, | ||
ssl_show_warn=False, | ||
http_auth=("admin", "admin"), | ||
) | ||
``` | ||
|
||
## Initialize Logger | ||
Initialize a logger, named "OpenSearchLogs", that emits logs to OpenSearch, and a console handler, both set to the INFO level, are initialized. The console handler is then added to the logger. For every log line processed by this setup, a corresponding OpenSearch document is created. This approach supports structured and comprehensive logging because each document can include extensive metadata within it. | ||
|
||
```python | ||
# Initialize a logger named "OpenSearchLogs" for OpenSearch & set log level to INFO | ||
print("Initializing logger...") | ||
os_logger = logging.getLogger("OpenSearchLogs") | ||
os_logger.setLevel(logging.INFO) | ||
|
||
# Create a console handler | ||
console_handler = logging.StreamHandler() | ||
console_handler.setLevel(logging.INFO) | ||
|
||
# Add console handler to the logger | ||
os_logger.addHandler(console_handler) | ||
``` | ||
|
||
## Custom Handler For Logs | ||
Define a custom handler that logs to OpenSearch: | ||
|
||
```python | ||
class OpenSearchHandler(logging.Handler): | ||
# Initializer / Instance attributes | ||
def __init__(self, opensearch_client): | ||
logging.Handler.__init__(self) | ||
self.opensearch_client = opensearch_client | ||
|
||
# Build index name (e.g., "logs-YYYY-MM-DD") | ||
def _build_index_name(self): | ||
return f"logs-{datetime.date(datetime.now())}" | ||
|
||
# Emit logs to the OpenSearch cluster | ||
def emit(self, record): | ||
document = { | ||
"timestamp": datetime.fromtimestamp(record.created).isoformat(), | ||
"name": record.name, | ||
"level": record.levelname, | ||
"message": record.getMessage(), | ||
"source": { | ||
"file": record.pathname, | ||
"line": record.lineno, | ||
"function": record.funcName, | ||
}, | ||
"process": { | ||
"id": record.process, | ||
"name": record.processName | ||
}, | ||
"thread": { | ||
"id": record.thread, | ||
"name": record.threadName | ||
}, | ||
} | ||
|
||
# Write the log entry to OpenSearch, handle exceptions | ||
self.opensearch_client.index( | ||
index=self._build_index_name(), | ||
body=document, | ||
) | ||
``` | ||
|
||
## Create OpenSearch Handler and Add to Logger | ||
Create an instance of OpenSearchHandler and add it to the logger: | ||
|
||
```python | ||
print("Creating an instance of OpenSearchHandler and adding it to the logger...") | ||
# Create an instance of OpenSearchHandler and add it to the logger | ||
os_handler = OpenSearchHandler(opensearch_client) | ||
os_logger.addHandler(os_handler) | ||
``` | ||
|
||
## Setup Asynchronous Logging Using Queues | ||
Finally, let's setup asynchronous logging using Queues: | ||
|
||
```python | ||
print("Setting up asynchronous logging using Queues...") | ||
# Setup asynchronous logging using Queues | ||
log_queue = queue.Queue(-1) # no limit on size | ||
os_queue_handler = QueueHandler(log_queue) | ||
os_queue_listener = QueueListener(log_queue, os_handler) | ||
|
||
# Add queue handler to the logger | ||
os_logger.addHandler(os_queue_handler) | ||
|
||
# Start listening on the queue using the os_queue_listener | ||
os_queue_listener.start() | ||
``` | ||
|
||
## Clean Up | ||
Finally, let's clean up by stopping the queue listener: | ||
|
||
```python | ||
print("Cleaning up...") | ||
# Stop listening on the queue | ||
os_queue_listener.stop() | ||
print("Log Collection Guide has completed running") | ||
``` | ||
|
||
## Sample Code | ||
See [log_collection_sample.py](/samples/logging/log_collection_sample.py) for a working sample of the concepts in this guide. The script will create a logger named "OpenSearchLogs" and set the log level to INFO. It will then create an instance of OpenSearchHandler and add it to the logger. Finally, it will setup asynchronous logging using Queues and send a test log to the OpenSearch cluster. | ||
|
||
Exptected Output From Running [log_collection_sample.py](/samples/logging/log_collection_sample.py): | ||
|
||
``` | ||
""" | ||
Running Log Collection Guide | ||
Setting up connection with OpenSearch cluster... | ||
Initializing logger... | ||
Creating an instance of OpenSearchHandler and adding it to the logger... | ||
Setting up asynchronous logging using Queues... | ||
Logger is set up and listener has started. Sending a test log... | ||
This is a test log message | ||
Cleaning up... | ||
Log Collection Guide has completed running | ||
""" | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,116 @@ | ||
#!/usr/bin/env python | ||
|
||
# -*- coding: utf-8 -*- | ||
# SPDX-License-Identifier: Apache-2.0 | ||
# | ||
# The OpenSearch Contributors require contributions made to | ||
# this file be licensed under the Apache-2.0 license or a | ||
# compatible open source license. | ||
# | ||
# Modifications Copyright OpenSearch Contributors. See | ||
# GitHub history for details. | ||
|
||
import logging | ||
import queue | ||
from datetime import datetime | ||
from logging.handlers import QueueHandler, QueueListener | ||
from typing import Any | ||
|
||
import urllib3 | ||
|
||
from opensearchpy import OpenSearch | ||
|
||
urllib3.disable_warnings() | ||
|
||
|
||
def main() -> None: | ||
print("Collecting logs.") | ||
|
||
# Create a console handler | ||
console_handler: logging.StreamHandler = logging.StreamHandler() # type: ignore | ||
console_handler.setLevel(logging.INFO) | ||
|
||
# Setup connection with the OpenSearch cluster | ||
print("Setting up connection with OpenSearch cluster...") | ||
opensearch_client: Any = OpenSearch( | ||
"https://admin:admin@localhost:9200", | ||
use_ssl=True, | ||
verify_certs=False, | ||
ssl_show_warn=False, | ||
http_auth=("admin", "admin"), | ||
) | ||
|
||
# Initialize a logger named "OpenSearchLogs" for OpenSearch | ||
print("Initializing logger...") | ||
os_logger: logging.Logger = logging.getLogger("OpenSearchLogs") | ||
os_logger.setLevel(logging.INFO) | ||
|
||
# Add console handler to the logger | ||
os_logger.addHandler(console_handler) | ||
|
||
# Define a custom handler that logs to OpenSearch | ||
class OpenSearchHandler(logging.Handler): | ||
# Initializer / Instance attributes | ||
def __init__(self, opensearch_client: Any) -> None: | ||
super().__init__() | ||
self.os_client = opensearch_client | ||
|
||
# Build index name (e.g., "logs-YYYY-MM-DD") | ||
def _build_index_name(self) -> str: | ||
return f"logs-{datetime.date(datetime.now())}" | ||
|
||
# Emit logs to the OpenSearch cluster | ||
def emit(self, record: logging.LogRecord) -> None: | ||
document = { | ||
"timestamp": datetime.fromtimestamp(record.created).isoformat(), | ||
"name": record.name, | ||
"level": record.levelname, | ||
"message": record.getMessage(), | ||
"source": { | ||
"file": record.pathname, | ||
"line": record.lineno, | ||
"function": record.funcName, | ||
}, | ||
"process": {"id": record.process, "name": record.processName}, | ||
"thread": {"id": record.thread, "name": record.threadName}, | ||
} | ||
|
||
try: | ||
self.os_client.index( | ||
index=self._build_index_name(), | ||
body=document, | ||
) | ||
except Exception as e: | ||
print(f"Failed to send log to OpenSearch: {e}") | ||
logging.warning(f"Failed to send log to OpenSearch: {e}") | ||
raise | ||
|
||
print("Creating an instance of OpenSearchHandler and adding it to the logger...") | ||
# Create an instance of OpenSearchHandler and add it to the logger | ||
os_handler: OpenSearchHandler = OpenSearchHandler(opensearch_client) | ||
os_logger.addHandler(os_handler) | ||
|
||
print("Setting up asynchronous logging using Queues...") | ||
# Setup asynchronous logging using Queues | ||
log_queue: queue.Queue[logging.LogRecord] = queue.Queue(-1) # no limit on size | ||
os_queue_handler: logging.Handler = QueueHandler(log_queue) | ||
os_queue_listener: QueueListener = QueueListener(log_queue, os_handler) | ||
|
||
# Add queue handler to the logger | ||
os_logger.addHandler(os_queue_handler) | ||
|
||
# Start listening on the queue using the os_queue_listener | ||
os_queue_listener.start() | ||
|
||
print("Logger is set up and listener has started. Sending a test log...") | ||
# Logging a test message | ||
os_logger.info("This is a test log message") | ||
|
||
print("Cleaning up...") | ||
# Stop listening on the queue | ||
os_queue_listener.stop() | ||
print("Log Collection Guide has completed running") | ||
|
||
|
||
if __name__ == "__main__": | ||
main() |