Skip to content

Commit

Permalink
docs: update logging configuration documentation (#8721)
Browse files Browse the repository at this point in the history 
* docs: refactor existing content

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>

* docs: add tui image

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>

* docs: add details for other modules than jans-auth

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>

* docs: add default log location

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>

* docs: proofreading

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>

* docs: tui section changes

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>

* docs: add log reference for CN deployments

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>

---------

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>
  • Loading branch information
@ossdhaval
ossdhaval committed Jun 20, 2024
1 parent e0c566a commit 5011f41
Show file tree
Hide file tree
Showing 2 changed files with 129 additions and 56 deletions.
185 changes: 129 additions & 56 deletions docs/admin/config-guide/logging-configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,102 +7,175 @@ tags:

# Log Management

> Prerequisite: Know how to use the Janssen CLI in [command-line mode](config-tools/jans-cli/README.md)
Logging for Janssen Server modules is managed at the individual module level.
Meaning there is no single switch or configuration that will enable or disable
logs for all modules. Each module can be individually configured and can be
configured differently when it comes to logging.

To `view/update` logging configuration, let's get the information of logging Configuration.
Logging for `jans-auth` service is what we are going to discuss in detail
in this document.
Logging for other modules is configured by changing the module's
property values. Use the documentation on how to update configuration
properties for
corresponding modules to update logging related properties. For instance:

`/opt/jans/jans-cli/config-cli.py --info ConfigurationLogging`
[//]: # (TODO: not sure if the sections below exist in respective docs. But)
[//]: # (if not then we need to add this content and link it here)
- [Updating properties for Fido2 module]()
- [Updating properties for SCIM module]()

## Log Configuration For jans-auth

=== "Use Command-line"

Use the command line to perform actions from the terminal. Learn how to
use Jans CLI [here](./config-tools/jans-cli/README.md) or jump straight to
the [Using Command Line](#using-command-line)

=== "Use Text-based UI"

Use a fully functional text-based user interface from the terminal.
Learn how to use Jans Text-based UI (TUI)
[here](./config-tools/jans-tui/README.md) or jump straight to the
[Using-text-based-ui](#using-text-based-ui)

```text
Operation ID: get-config-logging
Description: Returns Jans Authorization Server logging settings.
Operation ID: put-config-logging
Description: Updates Jans Authorization Server logging settings.
Schema: /components/schemas/LoggingConfiguration

To get sample shema type /opt/jans/jans-cli/config-cli.py --schema <schma>, for example /opt/jans/jans-cli/config-cli.py --schema /components/schemas/LoggingConfiguration
=== "Use REST API"

Use REST API for programmatic access or invoke via tools like CURL or
Postman. Learn how to use Janssen Server Config API
[here](./config-tools/config-api/README.md) or Jump straight to the
[Using Configuration REST API](#using-configuration-rest-api)

## Using Command Line

In the Janssen Server, you can deploy and customize the Logging Configuration using the
command line. To get the details of Janssen command line operations relevant to
Logging configuration, you can check the operations under
`ConfigurationLogging` task using the
command below:

```bash title="Command"
/opt/jans/jans-cli/config-cli.py --info ConfigurationLogging
```

Table of Contents
=================
```text title="Sample Output"
Operation ID: get-config-logging
Description: Returns Jans Authorization Server logging settings
Operation ID: put-config-logging
Description: Updates Jans Authorization Server logging settings
Schema: Logging
* [Log Management](#log-management)
* [Find Logging Configuration](#find-logging-configuration)
* [Update Logging Configuration](#update-logging-configuration)
To get sample schema type /opt/jans/jans-cli/config-cli.py --schema <schema>, for example /opt/jans/jans-cli/config-cli.py --schema Logging
```

## Find Logging Configuration
### Find Logging Configuration

```text
```bash title="Command"
/opt/jans/jans-cli/config-cli.py --operation-id get-config-logging
```

Getting access token for scope https://jans.io/oauth/config/logging.readonly
```json title="Sample Output" linenums="1"
{
"loggingLevel": "INFO",
"loggingLayout": "text",
"httpLoggingEnabled": false,
"loggingLevel": "DEBUG",
"loggingLayout": "string",
"httpLoggingEnabled": true,
"disableJdkLogger": true,
"enabledOAuthAuditLogging": false,
"externalLoggerConfiguration": null,
"httpLoggingExcludePaths": null
"enabledOAuthAuditLogging": true,
"externalLoggerConfiguration": "string",
"httpLoggingExcludePaths": [
"string"
]
}

```

## Update Logging Configuration
### Update Logging Configuration

To update logging configuration, get the schema first:
```bash title="Command"
/opt/jans/jans-cli/config-cli.py --schema Logging > /tmp/log-config.json
```
The schema can now be found in the log-config.json file.
Check the [update logging schema model](https://gluu.org/swagger-ui/?url=https://raw.githubusercontent.com/JanssenProject/jans/vreplace-janssen-version/jans-config-api/docs/jans-config-api-swagger.yaml#/Configuration%20%E2%80%93%20Logging/put-config-logging)

```commandline
/opt/jans/jans-cli/config-cli.py --schema /components/schemas/LoggingConfiguration > /tmp/log-config.json
let's update the schema:
```bash title="Command"
nano /tmp/log-config.json
```

As seen below, I have added `loggingLevel` for the value `INFO`
and `enabledOAuditLogging` for the value `false`.

```json title="Input"
{
"loggingLevel": "FATAL",
"loggingLayout": "text",
"loggingLevel": "INFO",
"loggingLayout": "string",
"httpLoggingEnabled": true,
"disableJdkLogger": true,
"enabledOAuthAuditLogging": false,
"externalLoggerConfiguration": null,
"externalLoggerConfiguration": "string",
"httpLoggingExcludePaths": [
"/auth/img",
"/auth/stylesheet"
"string"
]
}
```

let's update the schema:
```text
nano /tmp/log-config.json
```

Here I have updated `loggingLevel` to `DEBUG` and `enabledOAuditLogging` to `true` as below image.

![updated logging](../../assets/image-cl-update-logging-03042021.png)


Let's do the operation:

```commandline
/opt/jans/jans-cli/config-cli.py --operation-id put-config-logging --data /tmp/log-config.json
```bash title="Command"
/opt/jans/jans-cli/config-cli.py --operation-id put-config-logging \
--data /tmp/log-config.json
```

You will get the updated result as below:

```text
Getting access token for scope https://jans.io/oauth/config/logging.write
Server Response:
```json title="Sample Output" linenums="1"
{
"loggingLevel": "DEBUG",
"loggingLayout": "json",
"httpLoggingEnabled": false,
"disableJdkLogger": false,
"enabledOAuthAuditLogging": true,
"externalLoggerConfiguration": null,
"loggingLevel": "INFO",
"loggingLayout": "string",
"httpLoggingEnabled": true,
"disableJdkLogger": true,
"enabledOAuthAuditLogging": false,
"externalLoggerConfiguration": "string",
"httpLoggingExcludePaths": [
"/auth/img",
"/auth/stylesheet"
"string"
]
}
```

## Using-text-based-ui

In Janssen, You can manage Logging configuration using
the [Text-Based UI](./config-tools/jans-tui/README.md) also.

You can start TUI using the command below:

```bash title="Command"
sudo /opt/jans/jans-cli/jans_cli_tui.py
```
### Logging Screen

* Navigate to `Auth Server` -> `Logging` to open the Logging screen as shown
in the image below.

* Logging screen allows the administrator to set logging parameters as per
the requirements.


![image](../../assets/tui-logging-config.png)

## Using Configuration REST API

Janssen Server Configuration REST API exposes relevant endpoints for managing
and configuring logging. Endpoint details are published in the [Swagger
document](./../reference/openapi.md).

## Default Log Location

On a VM installation, logs for `jans-auth` module are generated at
`/opt/jans/jetty/jans-auth/logs/`.

## Cloud-Native Deployments

Logging configuration for a cloud-native deployment is [detailed here](../kubernetes-ops/logs.md)
Binary file added docs/assets/tui-logging-config.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 5011f41

Please sign in to comment.