Logging and Traceability

Joynare Nexus features a production-grade, structured logging framework with support for file-based storage, rotation, and dynamic routing.

Structured Logging

All logs are output in a structured format (Text by default, JSON supported). This makes it easy for both humans and machines to parse execution data.

Key Attributes

• time: The timestamp of the log entry.
• level: The severity (INFO, ERROR, WARN, DEBUG).
• traceId: A unique ID correlating all logs within a single execution.
• service: The name of the flow or adapter being executed.
• step: The specific step being executed (if applicable).
• duration: How long the operation took.

---

1. File-Based Logging & Rotation

By default, Joynare Nexus logs to files in the logs/ directory.

Configuration (config/logging.yaml)

You can configure rotation rules and default paths in the central logging config:

logging:
  default:
    path: "logs/nexus.log"
    level: "INFO"
    format: "text" # or "json"
    rotation:
      maxSize: 100    # MB before rotation
      maxBackups: 5   # Number of old files to keep
      maxAge: 28      # Days to keep files
      compress: true  # Compress old logs (.gz)

---

2. Dynamic Log Routing

Joynare Nexus allows you to isolate logs for specific business logic through a system of "Log Targets".

A. Default Global Logging

By default, all flow and adapter executions are logged to the global logs/nexus.log file. Errors are additionally mirrored to logs/errors.log. This prevents the creation of too many small log files.

B. Defining a Log Target

You can route a specific flow or adapter to a custom file by adding logTarget to its YAML definition.

# flows/orders/ProcessOrder/flow.yaml
name: "ProcessOrder"
namespace: "orders"
logTarget: "order-audit" # Identifies which log settings to use

C. Customizing Target Settings

Once you have defined a logTarget in your flow, you can customize its behavior in config/logging.yaml. The engine matches the logTarget from the flow to the name field in the custom list.

# config/logging.yaml
logging:
  # ... default settings ...
  custom:
    - name: "order-audit"       # Matches the logTarget in flow.yaml
      path: "logs/orders/audit.log"
      level: "DEBUG"            # Detailed logging for this specific target
      rotation:
        maxBackups: 100         # Keep more history than default

TIP

Smart Inheritance: If you leave out rotation settings for a custom logger, it will automatically inherit them from the default section. You only need to specify what you want to change.

D. Ad-hoc Log Targets

If you specify a logTarget in a flow that is not defined in config/logging.yaml, the engine will:

1. Automatically create a log file at logs/<target-name>.log.
2. Automatically create any missing parent directories.
3. Apply the global default rotation and level settings.

---

3. Automated Execution Tracing

The engine automatically logs every lifecycle event:

1. Service Start: Logs when a flow/adapter begins.
2. Step Auditing: Logs each step's entry, exit, duration, and errors.
3. Correlation ID (TraceID): Every request has a unique traceId propagated to all nested calls.

---

4. User-Defined Logging

Use the system.utils:Log service to manually record custom events within your business logic. This service also supports dynamic targets.

- name: "ManualAudit"
  type: "invoke"
  service: "system.utils:Log"
  input:
    level: "INFO"
    message: "Critical operation performed by ${user}"
    target: "security-audit" # Routes to security-audit.log (and uses its config if defined)

---

Viewing Logs

Logs are primarily stored in the logs/ directory.

• Real-time Tail: Get-Content logs/nexus.log -Wait (PowerShell) or tail -f logs/nexus.log (Linux).
• Search by Trace: Use grep or your editor to find all entries for a specific traceId.