> For the complete documentation index, see [llms.txt](https://morningheartgames.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/logging.md).

# Logging

> Online doc: <https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/logging?fallback=true>

Logging provides category-filtered runtime diagnostics for the toolkit. It is controlled through `GASConfiguration.loggingSettings`.

## What It Does

| Type                  | Responsibility                                                                 |
| --------------------- | ------------------------------------------------------------------------------ |
| `Logger`              | Central logging API.                                                           |
| `LogEntry`            | Structured log entry.                                                          |
| `LogFormatter`        | Formats log messages.                                                          |
| `LogLevel`            | None, Error, Warning, Info, Debug, Verbose.                                    |
| `LogCategory`         | System, Ability, Effect, Attribute, Tag, Cue, Task, Targeting, Input, Montage. |
| `ILogBackend`         | Output backend interface.                                                      |
| `UnityConsoleBackend` | Unity Console output.                                                          |
| `LogConfigWindow`     | Editor configuration window.                                                   |

## When To Use It

Use logging when:

* Ability activation fails and the ASC Events tab is not enough.
* Effects apply but modifiers do not change attributes.
* Tags are added/removed by unexpected owners.
* Input bindings are present but activations do not happen.
* Cues or targeting flows need detailed runtime traces.
* You are writing a custom extension and need diagnostics.

## Editor Setup

1. Open `Tools > Gameplay Ability Toolkit > Dashboard`.
2. Select or create `GASConfiguration`.
3. In the Inspector, expand `Logging Settings`.
4. Set `Enable Logging`.
5. Choose `Min Log Level`.
6. Choose `Enabled Categories`.
7. Enable `Unity Console`.
8. Optionally set category-specific log levels.
9. Reproduce the issue in Play Mode and filter Unity Console by category text.

## Configuration Fields

| Field                | Meaning                                                |
| -------------------- | ------------------------------------------------------ |
| `enableLogging`      | Master switch.                                         |
| `minLogLevel`        | Global minimum severity.                               |
| `enabledCategories`  | Bitmask of categories to emit.                         |
| `enableUnityConsole` | Writes to Unity Console backend.                       |
| `systemLogLevel`     | Override for ASC lifecycle and setup.                  |
| `abilityLogLevel`    | Override for grant, activation, cancellation, failure. |
| `effectLogLevel`     | Override for apply, execute, stack, remove.            |
| `attributeLogLevel`  | Override for value changes and modifier application.   |
| `tagLogLevel`        | Override for tag operations.                           |
| `taskLogLevel`       | Override for task activation/finish/cancel.            |
| `inputLogLevel`      | Override for input dispatch and binding.               |
| `cueLogLevel`        | Override for cue playback.                             |
| `targetingLogLevel`  | Override for targeting flows.                          |

## Runtime Flow

```mermaid
flowchart TD
    Subsystem["Runtime subsystem"] --> Logger["Logger"]
    Logger --> Settings["GASConfiguration.loggingSettings"]
    Settings --> Level["Level filter"]
    Settings --> Category["Category filter"]
    Level --> Backend["UnityConsoleBackend or custom backend"]
    Category --> Backend
```

## Debugging Profiles

| Issue                            | Suggested categories         |
| -------------------------------- | ---------------------------- |
| Ability does not activate        | Ability, Tag, Input, Effect. |
| Effect applies but stat is wrong | Effect, Attribute, Tag.      |
| Input source not working         | Input, Ability.              |
| Cue missing                      | Cue, Effect, Tag.            |
| Targeting stuck                  | Targeting, Input, Ability.   |
| Montage timing issue             | Montage, Task, Ability.      |

## Common Mistakes

| Mistake                                       | Result                     | Fix                                      |
| --------------------------------------------- | -------------------------- | ---------------------------------------- |
| Leaving Verbose enabled globally              | Console noise and overhead | Use category-specific overrides.         |
| Disabling Unity Console and no custom backend | Logs disappear             | Enable a backend.                        |
| Looking only at Info logs                     | Missed debug traces        | Temporarily raise the relevant category. |
| Logging every frame in custom code            | Performance and noise      | Log state changes, not steady state.     |

## Extension Points

* Implement `ILogBackend`.
* Register or route custom backend output in your project bootstrap.
* Use existing categories when extending toolkit systems.
* Add a custom category only if the existing category list cannot describe the subsystem.

## Examples and Tests

* Arena Demo: useful for combat flow debugging.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Systems/TargetingCueMontageLoggingDeepContractTests.cs`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/logging.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.