{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Logging\n",
    "\n",
    ".. contents:: :local:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "Logging is implemented using standard Python logging module. skyllh package adds support to multiprocessing logging."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup\n",
    "\n",
    "Analyzer has to set up the main logger and at least one handler for it. Necessary imports:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# configuration file with default values for logging setup.\n",
    "from skyllh.core.config import (\n",
    "    Config,\n",
    ")\n",
    "\n",
    "# Logging setup utilities.\n",
    "from skyllh.core.logging import (\n",
    "    get_logger,\n",
    "    setup_logger,\n",
    "    setup_logging,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default configuration contains a `logging` field with default logging settings"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'multiproc': {'ncpu': None},\n",
       " 'logging': {'log_level': 'INFO',\n",
       "  'log_format': '%(asctime)s %(processName)s %(name)s %(levelname)s: %(message)s',\n",
       "  'enable_tracing': False},\n",
       " 'project': {'working_directory': '.'},\n",
       " 'repository': {'base_path': None, 'download_from_origin': True},\n",
       " 'units': {'internal': {'angle': Unit(\"rad\"),\n",
       "   'energy': Unit(\"GeV\"),\n",
       "   'length': Unit(\"cm\"),\n",
       "   'time': Unit(\"s\")},\n",
       "  'defaults': {'fluxes': {'angle': Unit(\"rad\"),\n",
       "    'energy': Unit(\"GeV\"),\n",
       "    'length': Unit(\"cm\"),\n",
       "    'time': Unit(\"s\")}}},\n",
       " 'datafields': {'run': 4,\n",
       "  'ra': 4,\n",
       "  'dec': 4,\n",
       "  'ang_err': 4,\n",
       "  'time': 4,\n",
       "  'log_energy': 4,\n",
       "  'true_ra': 8,\n",
       "  'true_dec': 8,\n",
       "  'true_energy': 8,\n",
       "  'mcweight': 8},\n",
       " 'caching': {'pdf': {'MultiDimGridPDF': False}}}"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cfg = Config()\n",
    "cfg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two functions that can be used to setup a logger:\n",
    "* `setup_logging` in normal scripts should be used in analysis scripts by the user\n",
    "* `setup_logger` is more advanced and can be used for custom handler behavior"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Logger is setup with the following function call. Analyzer can define all desired logging properties. \n",
    "Required arguments are `cfg` and `name`. Remaining arguments default to what is defined in the config file if set to None."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "logger = setup_logging(\n",
    "    cfg=cfg,\n",
    "    name=__name__,\n",
    "    log_format='[%(asctime)s] %(name)s - %(levelname)s - %(message)s',\n",
    "    log_level='DEBUG',\n",
    "    console=True,\n",
    "    log_file=None,\n",
    "    reconfigure=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The important thing of `setup_logging` is that it takes care of setting up the skyllh package logger **and** the user-defined script logger by calling `setup_logger` twice."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In `setup_logger`, where some more arguments are available for advanced custom logging configuration.\n",
    "\n",
    "`setup_logger` allows to define different logging levels for the console and log file, and may or may not propagate handlers to ancestor loggers. However, these settings are mostly not needed for the general user, and are therefore not exposed in any example scripts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "logger = setup_logger(\n",
    "    cfg=cfg,\n",
    "    name=__name__,\n",
    "    log_format='[%(asctime)s] %(name)s - %(levelname)s - %(message)s',\n",
    "    log_level='DEBUG',\n",
    "    console=True,\n",
    "    console_level='DEBUG',\n",
    "    log_file=None,\n",
    "    file_level='DEBUG',\n",
    "    file_mode='a',\n",
    "    propagate=False,\n",
    "    clear_existing_handlers=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If a `log_file` name is passed, the file is created by default in the working directory defined in the configuration.\n",
    "\n",
    "`log_file` absolute paths are also allowed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To generate logs inside skyllh package one has to get the logger for the given class/function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "logger = get_logger(__name__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To log an event we use the logging function of a desired level, e.g.:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "[2026-03-23 14:21:33,953] __main__ - WARNING - This is a warning.\n"
     ]
    }
   ],
   "source": [
    "logger.warning('This is a warning.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The list of logging levels can be found [here](https://docs.python.org/3/library/logging.html#levels)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "skyllh_dev (3.14.2)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.14.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}