Merge pull request #255 from SAP/impr-custom-fields-docs

Update documentation

Author: christiand93

docs/configuration/custom-fields-format.md

@@ -6,10 +6,13 @@ nav_order: 4
 permalink: /configuration/custom-fields-format
 ---
 
-# Custom fields format
+# Custom fields format and type conversion
 
-As described in [Custom Fields](/cf-nodejs-logging-support/general-usage/custom-fields), the library will automatically detect which logging service your app is bound to and set the logging format accordingly.
-However, it is also possible to force the logging format by setting the property `customFieldsFormat`.
+
+
+As described in [Custom Fields](/cf-nodejs-logging-support/general-usage/custom-fields), the library supports different formats for logging custom fields to ensure compatibility with SAP logging services.
+When using user-provided services or running in environments without service bindings, you might want to explicitly set the custom fields format.
+Besides programmatic configuration, this can also be achieved via by adding the following settings to your configuration file.
 
 Example:
 

docs/configuration/fields.md

@@ -87,7 +87,7 @@ Each field, i.e., its source, format and behavior is defined by a set required a
 
 Read more on each available property below.
 
-### Property: name (required)
+### Property: `name` (required)
 
   * **Type:** `string`
   * **Description:** Assign field name.

docs/general-usage/04-custom-fields.md

@@ -8,70 +8,101 @@ permalink: /general-usage/custom-fields
 
 # Custom Fields
 
-You can use the custom field feature to add custom fields to your logs.
-
+Custom fields allow you to enrich your log messages with additional context by attaching key-value pairs.
+This is particularly useful for adding metadata that can help with filtering, searching, and analyzing logs.
 
 ## Format and type transformation for SAP logging services
 
-The library will automatically detect which logging service is bound to your app and will set the custom field format accordingly.
+While the library can be used independently of SAP logging services, it provides built-in support for logging custom fields compatible with [SAP Application Logging Service](https://help.sap.com/docs/application-logging-service) and [SAP Cloud Logging](https://help.sap.com/docs/cloud-logging).
+This includes proper formatting and type conversion of custom fields to ensure compatibility with the respective logging service:
+
+- **SAP Application Logging**: Custom fields are formatted as key-value pairs within a special `#cf` field in the log message. The values are converted to strings to ensure compatibility with the service's field type requirements.
+- **SAP Cloud Logging**: Custom fields are added as top-level fields in the log message. By default, values are also converted to strings to prevent type mismatches during indexing. However, you can configure the library to retain the original types of custom field values if needed.
+
+When deploying your application to SAP BTP Cloud Foundry, the library automatically detects logging service bindings and sets the custom field format accordingly.
+
+### Overriding the custom fields format
+
+There are cases where you might want to override the default behavior:
+- When using the library in an environment without a logging service binding, e.g., on Kubernetes.
+- When using a user-provided service where the logging service type cannot be detected correctly.
+- When you want to disable custom fields logging entirely.
 
-For local testing purposes you can enforce a specific format like this:
+In such cases, you can explicitly set the desired custom fields format programmatically:
 
 ```js
+import { CustomFieldsFormat } from "@sap/cf-nodejs-logging-support";
+
+log.setCustomFieldsFormat(CustomFieldsFormat.ApplicationLogging);
+// or
 log.setCustomFieldsFormat("application-logging");
-// possible values: "disabled", "all", "application-logging", "cloud-logging", "default"
 ```
 
-Alternatively, you can force the logging format by setting a configuration file as explained in [Custom Fields Format](/cf-nodejs-logging-support/configuration/custom-fields-format).
+Available formats are:
 
-### SAP Application Logging
+| Format Constant | String Value | Description |
+|-----------------|--------------|-------------|
+| `CustomFieldsFormat.ApplicationLogging` | `application-logging` | Use this format to log custom fields compatible with SAP Application Logging Service. |
+| `CustomFieldsFormat.CloudLogging` | `cloud-logging` | Use this format to log custom fields compatible with SAP Cloud Logging. |
+| `CustomFieldsFormat.All` | `all` | Use this format to log custom fields compatible with both SAP Application Logging Service and SAP Cloud Logging. |
+| `CustomFieldsFormat.Disabled` | `disabled` | Disable custom fields logging. |
+| `CustomFieldsFormat.Default` | `default` |  Same as `cloud-logging` format. |
 
-In case you want to use this library with SAP Application Logging Service you need to register your custom fields.
-Please make sure to call the registration exactly once globally before logging any custom fields.
-Registered fields will be indexed based on the order given by the provided field array.
+Alternatively, you can force the logging format setting using a configuration file as explained in [Advanced Configuration](/cf-nodejs-logging-support/configuration).
 
-Custom fields are converted and printed as string values independent of their original type.
+### Overriding the custom fields type conversion
+
+By default, custom field values are converted to strings to avoid type mismatches during indexing.
+While this behavior cannot be changed for the custom fields format used for SAP Application Logging, it can be adjusted for SAP Cloud Logging as follows:
 
 ```js
-log.registerCustomFields(["field"]);
-info("Test data", {"field": 42}); 
-// ... "msg":"Test data" 
-// ... "#cf": {"string": [{"k":"field","v":"42","i":0}]}...
+import { CustomFieldsTypeConversion } from "@sap/cf-nodejs-logging-support";
+
+log.setCustomFieldsTypeConversion(CustomFieldsTypeConversion.Retain);
 ```
 
-### SAP Cloud Logging
+Available type conversion options are:
+| Type Conversion Constant | Description |
+|--------------------------|-------------|
+| `CustomFieldsTypeConversion.Stringify` | Convert all custom field values to strings. This is the default behavior. |
+| `CustomFieldsTypeConversion.Retain` | Retain the original types of custom field values. |
+
+Alternatively, you can force the field type conversion setting using a configuration file as explained in [Advanced Configuration](/cf-nodejs-logging-support/configuration).
 
-When using the library with SAP Cloud Logging, custom fields get added as top-level fields.
-Registering custom fields is not required in this case.
+Keep in mind that retaining original types may lead to indexing issues if the same custom field is logged with different types across log entries.
 
-By default all custom field values get stringified, which can help to prevent field type mismatches when indexing to SAP Cloud Logging.
-However, if you want to retain the original type of your custom fields, you can change the type conversion configuration accordingly:
+### Registering custom fields for SAP Application Logging
+
+When using SAP Application Logging Service, it is necessary to register custom fields before logging them.
+Please make sure to do the registration exactly once globally before logging any custom fields.
+Registered fields will be indexed based on the order given by the provided field array.
 
 ```js
-log.setCustomFieldsTypeConversion(CustomFieldsTypeConversion.Retain)
+log.registerCustomFields(["field"]);
 info("Test data", {"field": 42}); 
 // ... "msg":"Test data" 
-// ... "field": 42
+// ... "#cf": {"string": [{"k":"field","v":"42","i":0}]}...
 ```
 
-## Adding custom fields
+## Logging custom fields
 
-In addition to logging messages as described in [Message Logs](/cf-nodejs-logging-support/general-usage/message-logs) you can attach custom fields as an object of key-value pairs as last parameter:
+In addition to logging messages as described in [Message Logs](/cf-nodejs-logging-support/general-usage/message-logs), you can attach custom fields by passing an object of key-value pairs as the last parameter.
+This allows enriching log messages with additional context information.
 
 ```js
 logger.info("My log message", {"field-a" :"value"}); 
 ```
 
-Another way of adding custom fields to messages is to set them for (child) loggers in *global* or *request* context.
-In result messages will contain the custom fields specified to the logger instance in use.
+Another way to add custom fields is by setting them on (child) logger instances, either globally or within a request context.
+When you do this, all messages logged by that logger will automatically include the specified custom fields, providing consistent context information across your logs.
 
 ```js
 logger.setCustomFields({"field-a": "value"})
 logger.info("My log message"); 
 ```
 
-You can also set custom fields globally by calling the same function on the global `log` instance.
-All logs, including request logs and logs by child loggers, will now contain the specified custom fields and values.
+You can also define custom fields globally by invoking the same method on the global `log` instance. 
+This ensures that all logs, including request logs and those emitted by child loggers, will automatically include the specified custom fields and their values.
 
 ```js
 log.setCustomFields({"field-b": "test"});

docs/index.markdown

@@ -9,9 +9,11 @@ nav_order: 1
 
 # CF Node.js Logging Support
 
-This library provides a bundle of targeted logging services for node.js applications running on Cloud Foundry which serves two main purposes:
+This library provides a bundle of targeted logging services for Node.js applications running on Cloud Foundry which serves two main purposes:
 It provides means to emit *structured application log messages* and instrument parts of your application stack to *collect request metrics*.
 
+The library is optimized for seamless integration with SAP BTP Cloud Foundry environment and its logging services [SAP Application Logging Service](https://help.sap.com/docs/application-logging-service) and [SAP Cloud Logging](https://help.sap.com/docs/cloud-logging).
+
 To get started follow our [Getting Started](/cf-nodejs-logging-support/getting-started/) chapters to install the library and learn how to integrate it with supported server frameworks.
 
 Head over to the [General Usage](/cf-nodejs-logging-support/general-usage) articles to find information about the main logging functions.