Skip to content

Logging

Railtracks emits log records for execution (node creation, completion, failures) but does not configure logging by default. To see logs in the terminal or a file, call enable_logging() from your application entry point (e.g. main, CLI, or server startup). This keeps the library from overriding your—or your host environment’s—logging setup.

Session/Flow logging parameters removed

Per-session and global-config logging options (logging_setting, log_file on Session, Flow, and set_config()) were removed. Use enable_logging(level=..., log_file=...) at startup (or RT_LOG_LEVEL / RT_LOG_FILE environment variables) as the single way to configure logging.

Example Logs 
[+3.525  s] RT          : INFO     - START CREATED Github Agent
[+8.041  s] RT          : INFO     - Github Agent CREATED create_issue
[+8.685  s] RT          : INFO     - create_issue DONE
[+14.333 s] RT          : INFO     - Github Agent CREATED assign_copilot_to_issue
[+14.760 s] RT          : INFO     - assign_copilot_to_issue DONE
[+17.540 s] RT          : INFO     - Github Agent CREATED assign_copilot_to_issue
[+18.961 s] RT          : INFO     - assign_copilot_to_issue DONE
[+23.401 s] RT          : INFO     - Github Agent DONE

Critical

Every log sent by Railtracks will contain a parameter in extras for session_id which will be uuid tied to the session the error was thrown in.

Configuring Logging

Enabling logging

Call enable_logging() once at application startup. The library never calls it automatically.

# Call once at application startup (main, CLI, or server entry point).
rt.enable_logging(level="INFO")

You can set the level and an optional log file path. If you omit them, Railtracks reads RT_LOG_LEVEL and RT_LOG_FILE from the environment (see below).

Logging Levels

Railtracks supports six logging levels aligned with the standard Python logging framework:

  1. DEBUG: Includes all logs. Ideal for local debugging.
  2. INFO: Includes INFO and above. Good default for development.
  3. WARNING: Includes WARNING and above. Recommended for production.
  4. ERROR: Includes recoverable issues that prevented part of the system from functioning correctly.
  5. CRITICAL: Includes severe failures that may cause shutdown.
  6. NONE: Disables all logging.
# Examples: set level when enabling logging.
rt.enable_logging(level="DEBUG")
rt.enable_logging(level="INFO")
rt.enable_logging(level="CRITICAL")
rt.enable_logging(level="NONE")

Logging Handlers

Console Handler

Once you call enable_logging(), a console handler is added and logs are printed to the terminal.

File Handler

Pass log_file to enable_logging() to also write logs to a file:

rt.enable_logging(level="INFO", log_file="my_logs.log")

File Handler logging level

Currently the logs outputted to the File Handler will be at DEBUG level for completeness. If you'd like us to support customizing this parameter, please open an issue at railtracks/issues

Custom Handlers

Railtracks uses the standard Python logging module. All framework loggers live under the RT name (e.g. RT.railtracks.state.state). To see only Railtracks logs and not third-party libraries (e.g. litellm), attach your handler to logging.getLogger("RT"):

import logging


class CustomHandler(logging.Handler):
    def emit(self, record):
        # Custom logging logic
        pass


# Attach to "RT" to see only Railtracks logs (not e.g. litellm).
logger = logging.getLogger("RT")
logger.addHandler(CustomHandler())

Example usage

Enable logging at startup

rt.enable_logging(level="DEBUG", log_file="my_logs.log")

Environment variables

You can set RT_LOG_LEVEL and RT_LOG_FILE in your environment (or .env). They are used as defaults when you call enable_logging() without arguments.

# Set in shell or .env; used as defaults when you call enable_logging() without arguments.
# RT_LOG_LEVEL=DEBUG
# RT_LOG_FILE=my_logs.log

Forwarding Logs to External Services

You can forward logs to services like Loggly, Sentry, or Conductr by attaching custom handlers. Refer to each provider's documentation for integration details.

import railtownai

RAILTOWN_API_KEY = "YOUR_RAILTOWN_API_KEY"
railtownai.init(RAILTOWN_API_KEY)

import logging
from loggly.handlers import HTTPSHandler

LOGGLY_TOKEN = "YOUR_LOGGLY_TOKEN"
https_handler = HTTPSHandler(
    url=f"https://logs-01.loggly.com/inputs/{LOGGLY_TOKEN}/tag/python"
)
logger = logging.getLogger("RT")
logger.addHandler(https_handler)

import sentry_sdk

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
    send_default_pii=True,  # Collects additional metadata
)

Log Message Examples

DEBUG Messages
Type Example
Runner Created RT.Runner : DEBUG - Runner <RUNNER_ID> is initialized
Node Created RT.Publisher: DEBUG - RequestCreation(current_node_id=<PARENT_NODE_ID>, new_request_id=<REQUEST_ID>, running_mode=async, new_node_type=<NODE_NAME>, args=<INPUT_ARGS>, kwargs=<INPUT_KWARGS>)
Node Completed RT.Publisher: DEBUG - <NODE_NAME> DONE with result <RESULT>
INFO Messages
Type Example
Initial Request RT : INFO - START CREATED <NODE_NAME>
Invoking Nodes RT : INFO - <PARENT_NODE_NAME> CREATED <CHILD_NODE_NAME>
Node Completed RT : INFO - <NODE_NAME> DONE
Run Data Saved RT.Runner : INFO - Saving execution info to .railtracks\<RUNNER_ID>.json
WARNING Messages
Type Example
Overwriting File RT.Runner : WARNING - File .railtracks\<RUNNER_ID>.json already exists, overwriting...
ERROR Messages
Type Example
Node Failed RT : ERROR - <NODE_NAME> FAILED