> ## Documentation Index
> Fetch the complete documentation index at: https://neo.tvk.company/llms.txt
> Use this file to discover all available pages before exploring further.

# Logger

> A centralized logging utility that provides structured logging with different severity levels for debugging and monitoring your Neo application.

## Examples

<Tabs>
  <Tab title="Basic Logging">
    <CodeGroup>
      ```dart Info Logging lines theme={null}
      NeoLogger.info("User login successful");
      ```

      ```dart Debug Information lines theme={null}
      NeoLogger.debug("API response received: ${response.statusCode}");
      ```

      ```dart Warning Messages lines theme={null}
      NeoLogger.warning("Deprecated method used in authentication flow");
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Error Handling">
    <CodeGroup>
      ```dart Error with Exception lines theme={null}
      try {
        // Some operation that might fail
        await riskyOperation();
      } catch (error, stackTrace) {
        NeoLogger.error(
          "Failed to process user data",
          error: error,
          stackTrace: stackTrace,
        );
      }
      ```

      ```dart Fatal Application Errors lines theme={null}
      try {
        await criticalSystemOperation();
      } catch (error, stackTrace) {
        NeoLogger.fatal(
          "Critical system failure - application cannot continue",
          error: error,
          stackTrace: stackTrace,
        );
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Development Debugging">
    <CodeGroup>
      ```dart Trace Execution Flow lines theme={null}
      NeoLogger.trace("Entering authentication method");
      // ... authentication logic
      NeoLogger.trace("Authentication completed successfully");
      ```

      ```dart State Change Logging lines theme={null}
      NeoLogger.debug("User preferences updated: theme=${user.theme}");
      NeoLogger.info("Navigation to dashboard screen");
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Debug vs Release Mode

NeoLogger automatically adjusts its logging behavior based on whether your app is running in debug or release mode:

<Info>
  **Debug Mode** (`flutter run`, development builds):

  * Shows ALL log levels: `trace`, `debug`, `info`, `warning`, `error`, `fatal`
  * Perfect for development and debugging

  **Release Mode** (`flutter build`, production builds):

  * Shows only: `info`, `warning`, `error`, `fatal`
  * Filters out `trace` and `debug` logs for clean user experience
</Info>

This means you can safely leave `trace` and `debug` calls throughout your codebase during development - they won't clutter the user experience in production builds.

## Methods

### NeoLogger.trace()

Logs detailed execution flow information, typically used for fine-grained debugging. Great for *tracing* your code.

#### Parameters

<ParamField path="message" type="String" required>
  The trace message to log.
</ParamField>

### NeoLogger.debug()

Logs debugging information useful during development and troubleshooting.

#### Parameters

<ParamField path="message" type="String" required>
  The debug message to log.
</ParamField>

### NeoLogger.info()

Logs general informational messages about application flow and events.

#### Parameters

<ParamField path="message" type="String" required>
  The informational message to log.
</ParamField>

### NeoLogger.warning()

Logs warning messages for potentially problematic situations that don't prevent execution.

#### Parameters

<ParamField path="message" type="String" required>
  The warning message to log.
</ParamField>

### NeoLogger.error()

Logs error messages with exception details and optional stack traces.

#### Required Parameters

<ParamField path="message" type="String" required>
  The error message describing what went wrong.
</ParamField>

<ParamField path="error" type="dynamic" required>
  The error or exception object that was caught.
</ParamField>

#### Optional Parameters

<ParamField path="stackTrace" type="StackTrace">
  The stack trace associated with the error for debugging purposes.
</ParamField>

### NeoLogger.fatal()

Logs critical error messages that typically indicate application-breaking issues.

#### Required Parameters

<ParamField path="message" type="String" required>
  The fatal error message describing the critical issue.
</ParamField>

<ParamField path="error" type="dynamic" required>
  The error or exception object that caused the fatal condition.
</ParamField>

#### Optional Parameters

<ParamField path="stackTrace" type="StackTrace">
  The stack trace associated with the fatal error.
</ParamField>

## Best Practices

* **Use appropriate log levels**: Choose the correct severity level for each message to enable proper filtering in production.
* **Avoid logging sensitive data**: Never log passwords, tokens, or other sensitive user information in production apps.
* **Use trace() and debug() freely**: These logs are automatically filtered out in release builds, so you can safely leave them in your code for development debugging.
* **Reserve info() for user-relevant events**: Since info logs appear in production, use them for events that might be relevant for support or monitoring.

## Integration Notes

* **Thread Safety**: All logging methods are thread-safe and can be called from any isolate.