botrun-log 0.1.0

A Python package for logging and ETL operations using Google BigQuery and PostgreSQL.

botrun-log

botrun-log 是一個用於將操作記錄儲存到 Google BigQuery 和 PostgreSQL 的 Python 套件，並提供 ETL 操作功能。此套件適用於記錄使用者行為，並能進行資料的分析和統計。

特色

• 支援 Google BigQuery 與 PostgreSQL 資料庫
• 針對機關和使用者的每日字元使用量進行 ETL 操作
• 支援加密操作細節，並使用 Google KMS 進行密鑰管理 待開發
• 支援多種操作類型的記錄和字元統計 待開發

安裝

1. 使用 pip 安裝

pip install botrun-log

2. 安裝開發環境需求

如果你想進行套件的開發或測試，可以使用以下命令安裝額外的開發需求：

pip install -e .[dev]

使用方式

1. 初始化 Logger

你可以使用 Logger 類別來初始化並選擇儲存資料的資料庫（BigQuery 或 PostgreSQL）。兩者的參數有一些不同，請根據你的需求進行配置。

BigQuery 初始化參數

from botrun_log import Logger

logger = Logger(
    department='test_org',
    db_type='bigquery',
    credentials_path='/path/to/your/credentials.json',  # Google Cloud Service Account 憑證路徑
    project_id='your_project_id',  # Google Cloud 專案 ID
    dataset_name='your_dataset_name'  # BigQuery 資料集名稱
)

PostgreSQL 初始化參數

from botrun_log import Logger

logger = Logger(
    department='test_org',
    db_type='postgresql',
    pg_config={
        'dbname': 'botrun_db',
        'user': 'botrun_user',
        'password': 'botrun_password',
        'host': 'localhost',
        'port': '5432'
    }  # PostgreSQL 連線配置
)

環境變數

botrun-log 使用 .env 檔案來讀取敏感資訊，如 AES 加密密鑰、Google Cloud 的憑證路徑、專案 ID 等。這樣可以避免在程式碼中寫入這些敏感資訊，提升安全性。你需要在專案根目錄建立 .env 檔案並設置以下變數：

BOTRUN_LOG_DEPARTMENT=test_org
BOTRUN_LOG_AES_KEY=your_base64_encoded_aes_key
BOTRUN_LOG_CREDENTIALS_PATH=/path/to/your/credentials.json
BOTRUN_LOG_PROJECT_ID=your_project_id
BOTRUN_LOG_DATASET_NAME=your_dataset_name

2. 插入記錄

LogEntry 是用來封裝每次操作的記錄物件。以下是必填與選填欄位的說明：

必填欄位

• timestamp: 操作的時間戳，必須是符合 ISO 8601 標準的時間格式。
• domain_name: 操作所屬的網域名稱。
• user_department: 使用者所屬的部門或機關。
• user_name: 使用者的名稱或帳號。
• source_ip: 發出操作請求的 IP 地址。
• session_id: 當前操作的工作階段 ID。
• action_type: 操作類型（如 "登入"、"登出"、"交談"、"上傳檔案" 等）。
• developer: 記錄這次操作的開發者名稱或寫入記錄的套件名稱。

選填欄位

• action_details: 操作的具體內容，可以是加密的 JSON 字串。
• user_agent: 使用者的客戶端資訊。
• resource_id: 與此次操作相關的資源 ID（如上傳的文件等）。

資料表

當你插入記錄時，資料會被寫入以下資料表：

• 如果使用 BigQuery：資料會插入到名為 {dataset_name}.{department}_logs 的表中，其中 {dataset_name} 是你在初始化 Logger 時指定的資料集名稱，{department} 是使用的部門名稱。
• 如果使用 PostgreSQL：資料會插入到名為 {department}_logs 的表中，其中 {department} 是使用的部門名稱。

插入記錄範例：

from botrun_log import LogEntry

log_entry = LogEntry(
    timestamp="2021-01-01T00:00:00Z",
    domain_name='botrun.ai',
    user_department="test_org",
    user_name="user_1",
    source_ip="127.0.0.1",
    session_id="session_1",
    action_type="交談",
    developer="JcXGTcW",
    action_details="~!@#$%^&*()_+台灣No.1",
    user_agent="user_agent",
    resource_id="resource_1"
)
logger.insert_log(log_entry)

3. 執行 ETL 操作

ETLManager 提供了針對日常字元使用量的 ETL 操作，並將結果寫入指定的資料庫中。根據使用的資料庫類型，BigQuery 和 PostgreSQL 的程式碼會略有不同。

BigQuery 的 ETL 操作

from botrun_log import ETLManager
from datetime import date

etl_manager = ETLManager(db_type='bigquery', credentials_path='/path/to/your/credentials.json')
etl_manager.write_etl_summary(department="test_org", date=date(2021, 1, 1))

在 BigQuery 中，write_etl_summary 會執行以下步驟：

1. 刪除與指定日期和部門相符的現有記錄。
2. 從每日的操作記錄中計算字元使用量並寫入 {dataset_name}.daily_character_usage 表中。

PostgreSQL 的 ETL 操作

from botrun_log import ETLManager
from datetime import date

etl_manager = ETLManager(db_type='postgresql', pg_config={
    'dbname': 'botrun_db',
    'user': 'botrun_user',
    'password': 'botrun_password',
    'host': 'localhost',
    'port': '5432'
})
etl_manager.write_etl_summary(department="test_org", date=date(2021, 1, 1))

在 PostgreSQL 中，write_etl_summary 會執行以下步驟：

1. 刪除與指定日期和部門相符的現有記錄。
2. 從每日的操作記錄中計算字元使用量並寫入 daily_character_usage 表中。

4. 獲取 ETL 結果

你可以使用 read_etl_summary 方法來讀取指定日期範圍內的字元使用量統計結果。

results = etl_manager.read_etl_summary(start_date=date(2021, 1, 1), end_date=date(2021, 1, 1), department="test_org")
for result in results:
    print(result)

測試

套件使用 pytest 進行單元測試。你可以在專案根目錄執行以下命令來跑測試：

pytest

貢獻

歡迎貢獻！如有問題或建議，請透過 issues 頁面與我們聯繫。

授權

此專案採用 MIT License 授權。