Skip to content

Commit

Permalink
.NET SDK custom log filter & platform compatibility docs (#469)
Browse files Browse the repository at this point in the history
* Add documentation for custom log filter

* Add docs on platform compatibility
  • Loading branch information
adams85 authored Aug 28, 2024
1 parent 6204190 commit c5e5b60
Showing 2 changed files with 58 additions and 10 deletions.
51 changes: 48 additions & 3 deletions website/docs/sdk-reference/dotnet.mdx
Original file line number Diff line number Diff line change
@@ -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` |

@@ -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`.
@@ -870,6 +892,27 @@ 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)+ and supports TLS 1.2 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](https://en.wikipedia.org/wiki/Ahead-of-time_compilation) deployment models.
Based on our tests, the SDK is compatible with the following runtimes/deployment models:
* .NET Framework 4.5+ (including Ngen)
* .NET Core 3.1, .NET 5+ (including Crossgen2/ReadyToRun and Native AOT)
* Mono 5.10+
* .NET for Android (formerly known as Xamarin.Android)
* .NET for iOS (formerly known as Xamarin.iOS)
* Unity 2021.3+ (Mono JIT)
* Unity 2021.3+ (IL2CPP)<sup><small>*</small></sup>
* Universal Windows Platform 10.0.16299.0+ (.NET Native)<sup><small>**</small></sup>
* WebAssembly (Mono AOT/Emscripten, also known as wasm-tools)
<sup><small>*</small></sup>Unity WebGL also works but needs a bit of extra effort: you will need to enable WebGL compatibility by calling the `ConfigCatClient.PlatformCompatibilityOptions.EnableUnityWebGLCompatibility` method. For more details, see [Sample Scripts](https://github.com/configcat/.net-sdk/tree/master/samples/UnityWebGL).<br/>
<sup><small>**</small></sup>To make the SDK work in Release builds on UWP, you will need to add `<Namespace Name="System.Text.Json.Serialization.Converters" Browse="Required All"/>` to your application's [.rd.xml](https://learn.microsoft.com/en-us/windows/uwp/dotnet-native/runtime-directives-rd-xml-configuration-file-reference) file. See also [this discussion](https://github.com/dotnet/runtime/issues/29912#issuecomment-638471351).
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:
@@ -904,7 +947,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 WebAssembly)</a>
- <a href="https://github.com/configcat/.net-sdk/tree/master/samples/MAUI" target="_blank">Sample Mobile/Windows Store App (.NET MAUI)</a>
## Guides
17 changes: 10 additions & 7 deletions website/docs/sdk-reference/java.mdx
Original file line number Diff line number Diff line change
@@ -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.
@@ -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

0 comments on commit c5e5b60

Please sign in to comment.