# Logging

powerGate uses [Apache log4net](<https://logging.apache.org/log4net/>) as core logging library, and additionally [PostSharp Diagnostics](<https://doc.postsharp.net/logging>) for extended Debug logging.

By default, all logs are stored in a logfile located in *'C:\\Users\\\{USER}\\AppData\\Local\\coolOrange\\powerGate\\Logs\\powerGate.log'*, containing only Warnings and Errors. For quick access, use the *powerGate Logs* shortcut in the Start menu.\
Backups of previous logfiles may also be available in this directory.

The log4net settings are stored in `C:\Program Files\coolOrange\Modules\powerGate\powerGate.log4net`.\
This configuration file controls logging for all powerGate components, including:
* ERP integrations with ERP Cmdlets and BOM Window
* Cmdlets for Fusion Manage
* APS Cmdlets

*Note:* Log messages from your customization scripts are written to the **coolOrange powerJobs** log. See the [powerJobs Processor logging](<inv:powerjobs_processor#logging>) and [powerJobs Client logging](<inv:powerjobs_client#logging>) guides for details.

Further information about log4net configurations can be found [here](<https://logging.apache.org/log4net/manual/configuration.html>).
<br>
<br>

## When to change the logging behavior?

When you have issues or when you want to get a more detailed knowledge about what powerGate is doing, you can increase the [logging level](<inv:powerjobs_processor#logging/log_level>).\
For examples on how to adjust log levels specifically for individual components, see the [powerPLM logging](<inv:powerplm#logging>) and [powerAPS logging](<inv:poweraps#logging>) sections.

:::{note}
Setting the log level to DEBUG enables [PostSharp Diagnostics](<https://doc.postsharp.net/logging>), which starts logging all function calls as well as any exceptions related to PowerShell (namespace *coolOrange.Powershell.Cmdlets*).\
Be aware that this significantly reduces performance!
:::

Additionally you can change the [logfile](<logging:LogFile>) location or integrate the logging mechanism into your administrative environment by using build in EventLogMessages etc.

## TRAFFIC logging (ERP only)

In addition to the standard log levels (DEBUG, INFO, WARN, ERROR, FATAL), all ERP Cmdlets support an additional level called **TRAFFIC** - positioned between *DEBUG* and *INFO*.\
It is used to trace all **requests** that are sent to the server, and the received **responses**.

```{code-block} xml
:linenos:

<level>
	<name value="TRAFFIC" />
	<value value="30001" />
</level>
```

In the following link you will find the default log levels associated with the numeric values they have at the bottom: [Level.cs](<http://svn.apache.org/repos/asf/logging/log4net/tags/log4net-1_2_9/src/Core/Level.cs>)

If you want to change the logging level for all appenders e.g. to "TRAFFIC", please visit the root logger and change the level in the lines:

```{code-block} xml
:linenos:

<level value="TRAFFIC" />
```

you can configure the required [logging level](<inv:powerjobs_processor#logging/log_level>). You could set the level to "DEBUG", than all the levels above Debug and also Debug will be logged.

:::{note}
When increasing the loglevel for the root logger, please make sure your favorite appenders minlevel is configured to allow logging messages with the specified level.
:::

powerGate allows you to customize the format of request and response logs using the following appender.

### TrafficPatternLayout

Each appender has its own layout that defines how the log-messages are formatted. By using the special Layout **powerGate.Erp.Client.Traffic.TrafficPatternLayout** you have the possibility to configure two new ConverstionPatterns: **RequestConversionPattern**, **ResponseConversionPattern**.

The **TrafficPatternLayout** has all the functionality of a simple [PatternLayout](<https://logging.apache.org/log4net/log4net-1.2.13/release/sdk/log4net.Layout.PatternLayout.html>) too. That means all logs that are not Requests or Responses can be configured by using the default **ConversionPattern** node.\
Therefore all the available conversion pattern names from [PatternLayout](<https://logging.apache.org/log4net/log4net-1.2.13/release/sdk/log4net.Layout.PatternLayout.html>) are available for the TrafficPatternLayout too.

### RequestConversionPattern

This pattern applies when a **request** gets logged and additionally you have access to following options:

```{code-block}

%Request{Protocol}
%Request{ProtocolVersion}
%Request{Method}
%Request{Url}
%Request{Headers}
%Request{Body}
```

For instance you are able to log something like this:

```{code-block} xml

<RequestConversionPattern value="Called: %Request{Method}% on %Request{Url}" />
```

This will result in logs like:\
*Called: GET on localhost:8080/pgs/ERP/MaterialService/Materials*

### ResponseConversionPattern

This pattern applies when a **response** gets logged and additionally you have access to following options:

```{code-block}

%Response{Protocol}
%Response{ProtocolVersion}
%Response{StatusCode}
%Response{Status}
%Response{Headers}
%Response{Body}
```

For instance you are able to log something like this:

```{code-block} xml

<ResponseConversionPattern value="Received: %Response{StatusCode}% %Response{Status}" />
```

This will result in logs like:\
*Received: 200 OK*

## LogFile

You can see, that there are multiple logging-Appenders used. If you want to change the [logging level](<inv:powerjobs_processor#logging/log_level>) in the logfile, please visit following appender:

```{code-block} xml

<appender name="FileAppender" type="log4net.Appender.RollingFileAppender">
```

In the lines

```{code-block} xml

<filter type="log4net.Filter.LevelRangeFilter">
	<levelMin value="WARN" />
	<levelMax value="FATAL" />
</filter>
```

you can configure the logginglevel. You could set the minimal filter level to "DEBUG", than all the levels between the range Debug and Fatal will be logged.

In the line

```{code-block} xml
:linenos:

<param name="File" value="${LOCALAPPDATA}\coolOrange\powerGate\Logs\powerGate.log" />
```

you can configure the outputpath and name of the logfile.

## PowerShell IDE

PowerShell IDE's like PowerShell console (and PowerShell ISE) are configured to show the logging levels in a different color.

```{code-block} xml

<mapping>
	<level value="DEBUG" />
	<foreColor value="Black" />
	<backColor value="White" />
</mapping>
<mapping>
	<level value="TRAFFIC" />
	<foreColor value="Black" />
	<backColor value="White" />
</mapping>
<mapping>
	<level value="INFO" />
	<backColor value="DarkGreen" />
</mapping>
<mapping>
	<level value="WARN" />
	<foreColor value="Black" />
	<backColor value="Yellow" />
</mapping>
<mapping>
	<level value="ERROR" />
	<backColor value="Red" />
</mapping>
<mapping>
	<level value="FATAL" />
	<backColor value="DarkRed" />
</mapping>
```

These and many other options can be configured in the appender named **ColoredConsoleAppender**.