Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

.NET SDK custom log filter & platform compatibility docs #469

Merged
merged 6 commits into from
Aug 28, 2024
Merged

.NET SDK custom log filter & platform compatibility docs #469

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
993f25b
Add documentation for custom log filter
adams85 Jul 31, 2024
52a2d6d
Add docs on platform compatibility
adams85 Jul 31, 2024
fc81ef0
Corrections to "Platform compatibility"
adams85 Aug 2, 2024
e06d25a
Fix formatting
adams85 Aug 2, 2024
cab8311
Minor correction
adams85 Aug 28, 2024
1e8548d
Add link
adams85 Aug 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 44 additions & 3 deletions website/docs/sdk-reference/dotnet.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,13 +102,15 @@ These are the available options on the `ConfigCatClientOptions` class:
| Properties | Description | Default |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `PollingMode` | Optional, sets the polling mode for the client. [More about polling modes](#polling-modes). | `PollingModes.AutoPoll()` |
| `ConfigFetcher` | Optional, [`IConfigCatConfigFetcher`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/ConfigService/IConfigCatConfigFetcher.cs) instance for downloading a config. | [`HttpClientConfigFetcher`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/ConfigService/HttpClientConfigFetcher.cs) |
| `ConfigCache` | Optional, [`IConfigCatCache`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Cache/IConfigCatCache.cs) instance for caching the downloaded config. | [`InMemoryConfigCache`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Cache/InMemoryConfigCache.cs) |
| `Logger` | Optional, [`IConfigCatLogger`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Logging/IConfigCatLogger.cs) instance for tracing. | [`ConsoleLogger`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Logging/ConsoleLogger.cs) (with WARNING level) |
| `LogFilter` | Optional, sets a custom log filter. [More about log filtering](#log-filtering). | `null` (none) |
| `BaseUrl` | Optional, sets the CDN base url (forward proxy, dedicated subscription) from where the SDK will download the config JSON. | |
| `HttpClientHandler` | Optional, `HttpClientHandler` to provide network credentials and proxy settings. [More about the proxy settings](#using-configcat-behind-a-proxy). | built-in `HttpClientHandler` |
| `HttpClientHandler` | Optional, `HttpClientHandler` to provide network credentials and proxy settings. [More about the proxy settings](#using-configcat-behind-a-proxy). | built-in `HttpClientHandler` |
| `HttpTimeout` | Optional, sets the underlying HTTP client's timeout. [More about the HTTP timeout](#http-timeout). | `TimeSpan.FromSeconds(30)` |
| `FlagOverrides` | Optional, sets the local feature flag & setting overrides. [More about feature flag overrides](#flag-overrides). | |
| `DataGovernance` | Optional, defaults to `Global`. Describes the location of your feature flag and setting data within the ConfigCat CDN. This parameter needs to be in sync with your Data Governance preferences. [More about Data Governance](../advanced/data-governance.mdx). Available options: `Global`, `EuOnly` | `Global` |
| `DataGovernance` | Optional, defaults to `Global`. Describes the location of your feature flag and setting data within the ConfigCat CDN. This parameter needs to be in sync with your Data Governance preferences. [More about Data Governance](../advanced/data-governance.mdx). Available options: `Global`, `EuOnly` | `Global` |
| `DefaultUser` | Optional, sets the default user. [More about default user](#default-user). | `null` (none) |
| `Offline` | Optional, determines whether the client should be initialized to offline mode. [More about offline mode](#online--offline-mode). | `false` |

Expand Down Expand Up @@ -703,10 +705,30 @@ ConfigCat.INFO [5000] Evaluating 'isPOCFeatureEnabled' for User '{"Identifier":
Returning 'True'.
```

### Custom logger implementation

By default, the SDK logs to [the console's standard output](https://learn.microsoft.com/en-us/dotnet/api/system.console.out) but it also allows you to inject any custom logger implementation via the `ConfigCatClientOptions.Logger` property.

Sample code on how to create a basic file logger implementation for ConfigCat client: <a href="https://github.com/configcat/.net-sdk/blob/master/samples/FileLoggerSample.cs" target="_blank">See Sample Code</a>

Another sample which shows how to implement an adapter to [the built-in logging framework](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/logging) of .NET Core/.NET 5+: <a href="https://github.com/configcat/.net-sdk/blob/master/samples/ASP.NETCore/WebApplication/Adapters/ConfigCatToMSLoggerAdapter.cs" target="_blank">See Sample Code</a>

### Log Filtering

You can define a custom log filter by providing a callback function via the `ConfigCatClientOptions.LogFilter` property. The callback will be called by the _ConfigCat SDK_ each time a log event occurs (and the event passes the minimum log level specified by the `IConfigCatLogger.LogLevel` property). That is, the callback allows you to filter log events by `level`, `eventId`, `message` or `exception`. The formatted message string can be obtained via `message.InvariantFormattedMessage`.
If the callback function returns `true`, the event will be logged, otherwise it will be skipped.

```cs
// Filter out events with id 1001 from the log.
LogFilterCallback logFilter = (LogLevel level, LogEventId eventId, ref FormattableLogMessage message, Exception? exception) => eventId != 1001;

var client = ConfigCatClient.Get("#YOUR-SDK-KEY#", options => options.LogFilter = logFilter);
```

:::caution
Please make sure that your log filter logic doesn't perform heavy computation and doesn't block the executing thread. A complex or incorrectly implemented log filter can degrade the performance of the SDK.
:::

## `GetAllKeysAsync()`

You can get all the setting keys from your configuration by calling the `GetAllKeysAsync()` method of the `ConfigCatClient`.
Expand Down Expand Up @@ -870,6 +892,23 @@ IConfigCatClient client = ConfigCatClient.Get("#YOUR-SDK-KEY#", options =>

The default timeout is 30 seconds.

## Platform compatibility

The _ConfigCat SDK_ supports all the widespread .NET JIT runtimes, everything that implements [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0)+ should work.
Starting with v9.3.0, it can also be used in applications that employ [trimmed self-contained](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trim-self-contained) or various ahead-of-time (AOT) compilation deployment models.

The SDK has been tested on the following .NET runtimes:
* .NET Framework 4.5+
* .NET Core 3.1, .NET 5+
* .NET 8 Native AOT
* UWP/WinUI (.NET MAUI 8)
* Mono JIT (Unity 2021.3+)
* Mono AOT (.NET MAUI 8 iOS)
* Mono WebAssembly AOT/Emscripten (ASP.NET Core Blazor 8)
* IL2CPP (Unity 2021.3+) - Unity WebGL also works but needs a bit of extra effort (see [sample scripts](https://github.com/configcat/.net-sdk/tree/master/samples/UnityWebGL))

We strive to provide an extensive support for the various .NET runtimes and versions. If you still encounter an issue with the SDK on some platform, please open a [GitHub issue](https://github.com/configcat/.net-sdk/issues/new/choose) or contact support.

## Troubleshooting

When the _ConfigCat SDK_ does not work as expected in your application, please check for the following potential problems:
Expand Down Expand Up @@ -904,7 +943,9 @@ When the _ConfigCat SDK_ does not work as expected in your application, please c
Check out our Sample Applications how they use the _ConfigCat SDK_:

- <a href="https://github.com/configcat/.net-sdk/tree/master/samples/ConsoleApp" target="_blank">Sample Console App</a>
- <a href="https://github.com/configcat/.net-sdk/tree/master/samples/ASP.NETCore" target="_blank">Sample Web App</a>
- <a href="https://github.com/configcat/.net-sdk/tree/master/samples/ASP.NETCore" target="_blank">Sample Multi-page Web App (ASP.NET Core MVC)</a>
- <a href="https://github.com/configcat/.net-sdk/tree/master/samples/BlazorWasm" target="_blank">Sample Single-page Web App (ASP.NET Core Blazor)</a>
- <a href="https://github.com/configcat/.net-sdk/tree/master/samples/MAUI" target="_blank">Sample Mobile/Windows Store App (.NET MAUI)</a>

## Guides

Expand Down
17 changes: 10 additions & 7 deletions website/docs/sdk-reference/java.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,11 +119,11 @@ These are the available options on the `Options` class:
| `cache(ConfigCache)` | Optional, sets a custom cache implementation for the client. [More about cache](#custom-cache). |
| `pollingMode(PollingMode)` | Optional, sets the polling mode for the client. [More about polling modes](#polling-modes). |
| `logLevel(LogLevel)` | Optional, defaults to `WARNING`. Sets the internal log level. [More about logging](#logging). |
| `logFilter(LogFilterFunction)` | Optional, sets a custom log filter. [More about log filtering](#log-filtering). |
| `flagOverrides(OverrideDataSourceBuilder, OverrideBehaviour)` | Optional, sets the local feature flag & setting overrides. [More about feature flag overrides](#flag-overrides). |
| `defaultUser(User)` | Optional, sets default user. [More about default user](#default-user). |
| `offline(boolean)` | Optional, defaults to `false`. Indicates whether the SDK should be initialized in offline mode. [More about offline mode](#online--offline-mode). |
| `hooks()` | Optional, used to subscribe events that the SDK sends in specific scenarios. [More about hooks](#hooks). |
| `logFilter(LogFilterFunction)` | Optional, sets a custom log filter. [More about log filtering](#log-filtering). |

:::caution
We strongly recommend you to use the `ConfigCatClient` as a Singleton object in your application.
Expand Down Expand Up @@ -874,16 +874,19 @@ Examples fo <a href="https://github.com/configcat/java-sdk/blob/master/samples/c

### Log Filtering

You can define a custom log filter option by implementing the `LogFilterFunction` interface. The `apply` method will be called by the _ConfigCat SDK_ each time a log event occurs (and the event passes the minimum log level specified by the `logLevel` option). That is, the `apply` method allows you to filter log events by `logLevel`, `eventId`, `message` or `exception`. The formatted message String can be obtained by calling `toString()` on the `message` parameter.
If the `apply` method returns with `true`, the event will be logged, otherwise it will be skipped.
You can define a custom log filter by implementing the `LogFilterFunction` interface. The `apply` method will be called by the _ConfigCat SDK_ each time a log event occurs (and the event passes the minimum log level specified by the `logLevel` option). That is, the `apply` method allows you to filter log events by `logLevel`, `eventId`, `message` or `exception`. The formatted message string can be obtained by calling `toString()` on the `message` parameter.
If the `apply` method returns `true`, the event will be logged, otherwise it will be skipped.

```java
// Filter out events with id 1001 from the log.
LogFilterFunction filterLogFunction = ( LogLevel logLevel, int eventId, Object message, Throwable exception) -> eventId != 1001;
// Filter out events with id 1001 from the log.
LogFilterFunction filterLogFunction = ( LogLevel logLevel, int eventId, Object message, Throwable exception) -> eventId != 1001;

ConfigCatClient client = ConfigCatClient.get("#YOUR-SDK-KEY#", options -> options.logFilter(filterLogFunction));
ConfigCatClient client = ConfigCatClient.get("#YOUR-SDK-KEY#", options -> options.logFilter(filterLogFunction));
```
> Please make sure that your log filter logic doesn't perform heavy computation and doesn't block the executing thread. A complex or incorrectly implemented log filter can degrade the performance of the SDK.

:::caution
Please make sure that your log filter logic doesn't perform heavy computation and doesn't block the executing thread. A complex or incorrectly implemented log filter can degrade the performance of the SDK.
:::

## Sample Apps

Expand Down
Loading