docs: add exhaustive complete logs reference guide (#5345)
Signed-off-by: James Elliott <james-d-elliott@users.noreply.github.com>pull/5346/head
James Elliott
GitHub
parent
63d2de7604
commit
eaddb57c27
|
|
@ -17,7 +17,9 @@ body:
|
|||
2. Please try to give as much information as possible for us to be able to reproduce the issue and provide a quick fix.
|
||||
3. Please ensure an issue does not already exist for this potential bug.
|
||||
4. Please only provide specific versions. Latest is not a version.
|
||||
5. Please read the [Troubleshooting Sanitization](https://www.authelia.com/r/sanitize) reference guide if you plan on sanitizing, removing, or adjusting any values for the logs or configuration files.
|
||||
5. Please read the [Troubleshooting](https://www.authelia.com/r/troubleshooting) reference guide:
|
||||
- Do not truncate any logs unless you are complying with the specific instructions in the [Logs](https://www.authelia.com/r/troubleshooting#logs) section.
|
||||
- If you plan on sanitizing, removing, or adjusting any values for the logs or configuration files please read the [Sanitization](https://www.authelia.com/r/troubleshooting#sanitization) section.
|
||||
6. Please consider including a [HTTP Archive File](https://www.authelia.com/r/har) if you're having redirection issues.
|
||||
- type: dropdown
|
||||
id: version
|
||||
|
|
@ -135,7 +137,10 @@ body:
|
|||
label: Logs (Authelia)
|
||||
description: |
|
||||
Provide complete logs with the log level set to debug or trace. Complete means from application start until the
|
||||
issue occurring. The template will automatically put this content in a code block so you can just paste it.
|
||||
issue occurring. This is clearly explained in the [Logs](https://www.authelia.com/r/troubleshooting#logs)
|
||||
section of the troubleshooting guide.
|
||||
|
||||
The template will automatically put this content in a code block so you can just paste it.
|
||||
render: shell
|
||||
validations:
|
||||
required: true
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ import (
|
|||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/valyala/fasthttp"
|
||||
"gopkg.in/yaml.v3"
|
||||
yaml "gopkg.in/yaml.v3"
|
||||
)
|
||||
|
||||
func newDocsDateCmd() *cobra.Command {
|
||||
|
|
@ -87,7 +87,17 @@ func docsDateRunE(cmd *cobra.Command, args []string) (err error) {
|
|||
)
|
||||
|
||||
if value, ok := frontmatter["date"]; ok {
|
||||
date = value.(time.Time)
|
||||
date, ok = value.(time.Time)
|
||||
|
||||
if !ok {
|
||||
var abspath string
|
||||
|
||||
if abspath, err = filepath.Abs(path); err != nil {
|
||||
abspath = path
|
||||
}
|
||||
|
||||
return fmt.Errorf("frontmatter for %s has an invalid date value: is %T with a value of %s", abspath, value, value)
|
||||
}
|
||||
}
|
||||
|
||||
dateGit := getDateFromGit(cwd, abs, commitFilter)
|
||||
|
|
|
|||
|
|
@ -17,7 +17,9 @@ body:
|
|||
2. Please try to give as much information as possible for us to be able to reproduce the issue and provide a quick fix.
|
||||
3. Please ensure an issue does not already exist for this potential bug.
|
||||
4. Please only provide specific versions. Latest is not a version.
|
||||
5. Please read the [Troubleshooting Sanitization](https://www.authelia.com/r/sanitize) reference guide if you plan on sanitizing, removing, or adjusting any values for the logs or configuration files.
|
||||
5. Please read the [Troubleshooting](https://www.authelia.com/r/troubleshooting) reference guide:
|
||||
- Do not truncate any logs unless you are complying with the specific instructions in the [Logs](https://www.authelia.com/r/troubleshooting#logs) section.
|
||||
- If you plan on sanitizing, removing, or adjusting any values for the logs or configuration files please read the [Sanitization](https://www.authelia.com/r/troubleshooting#sanitization) section.
|
||||
6. Please consider including a [HTTP Archive File](https://www.authelia.com/r/har) if you're having redirection issues.
|
||||
- type: dropdown
|
||||
id: version
|
||||
|
|
@ -97,7 +99,10 @@ body:
|
|||
label: Logs (Authelia)
|
||||
description: |
|
||||
Provide complete logs with the log level set to debug or trace. Complete means from application start until the
|
||||
issue occurring. The template will automatically put this content in a code block so you can just paste it.
|
||||
issue occurring. This is clearly explained in the [Logs](https://www.authelia.com/r/troubleshooting#logs)
|
||||
section of the troubleshooting guide.
|
||||
|
||||
The template will automatically put this content in a code block so you can just paste it.
|
||||
render: shell
|
||||
validations:
|
||||
required: true
|
||||
|
|
|
|||
|
|
@ -7,5 +7,5 @@
|
|||
package cmd
|
||||
|
||||
const (
|
||||
versionSwaggerUI = "4.18.2"
|
||||
versionSwaggerUI = "4.18.3"
|
||||
)
|
||||
|
|
|
|||
|
|
@ -182,8 +182,8 @@ By making a contribution to this project, I certify that:
|
|||
|
||||
This can be achieved in the following ways:
|
||||
|
||||
- While making the commit use `git commit --signoff`
|
||||
- To correct a single commit missing the sign off `git commit –-amend --signoff --no-edit`
|
||||
- While making the commit use `git commit --signoff` or `git commit -s`
|
||||
- To correct a single commit missing the sign off `git commit –-amend --no-edit --signoff` or `git commit --amend --no-edit -s`
|
||||
- To correct multiple commits missing the sign off `git rebase --signoff HEAD~2` (i.e. with 2 commits that are missing the sign off)
|
||||
|
||||
This can be achieved by using `git commit --signoff`. A single previous commit can be signed using
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
title: "Kasm Workspaces"
|
||||
description: "Integrating Kasm Workspaces with the Authelia OpenID Connect Provider."
|
||||
lead: ""
|
||||
date: 2023-04-25T23:07:05+2:00
|
||||
date: 2023-04-27T18:40:06+10:00
|
||||
draft: false
|
||||
images: []
|
||||
menu:
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ present in an environment.
|
|||
|
||||
The following section outlines some helpful information if you wish to sanitize your HAR file to share it with others.
|
||||
|
||||
For generic sanitization information see the [Troubleshooting Sanitization guide](troubleshooting-sanitizaiton.md).
|
||||
For generic sanitization information see the [Troubleshooting Sanitization guide](troubleshooting.md#sanitization).
|
||||
|
||||
### Security Sensitive Information
|
||||
|
||||
|
|
|
|||
|
|
@ -1,42 +0,0 @@
|
|||
---
|
||||
title: "Troubleshooting Sanitization"
|
||||
description: "This guide describes and helps users sanitize provided files to hide privacy related values for troubleshooting"
|
||||
lead: "This guide describes and helps users sanitize provided files to hide information for privacy."
|
||||
date: 2022-09-16T14:21:05+10:00
|
||||
draft: false
|
||||
images: []
|
||||
menu:
|
||||
reference:
|
||||
parent: "guides"
|
||||
weight: 220
|
||||
toc: true
|
||||
aliases:
|
||||
- /r/sanitize
|
||||
---
|
||||
|
||||
Some users may wish to hide their domain in files provided during troubleshooting. While this is discouraged, if a user
|
||||
decides to perform this action it's critical for these purposes that you hide your domain in a very specific
|
||||
way. Most editors allow replacing all instances of a value, utilizing this is essential to making troubleshooting
|
||||
possible.
|
||||
|
||||
## General Rules
|
||||
|
||||
1. Only replace the purchased portion of domains:
|
||||
- For example if you have `auth.abc123.com` and `app.abc123.com` they
|
||||
should become `auth.example.com` and `app.example.com`, i.e. replace all instances of `abc123.com` with `example.com`.
|
||||
2. Make sure value replaced is replaced with a unique value:
|
||||
- For example if you replace `abc123.com` with `example.com` DO NOT replace any other value other than `abc123.com` with
|
||||
`example.com`. The same rule applies to IP addresses, usernames, and groups.
|
||||
3. Make sure the value replaced is replaced across logs, configuration, and any references:
|
||||
- For example if you replace `abc123.com` with `example.com` in your configuration, make exactly the same replacement
|
||||
for the log files.
|
||||
4. Make sure this consistency is followed for all communication regarding a single issue.
|
||||
|
||||
## Multiple Domains
|
||||
|
||||
*__Replacement Value:__* `example#.com` (where `#` is a unique number per domain)
|
||||
|
||||
In instances where there are multiple domains it's recommended these domains are replaced with `example1.com`,
|
||||
`example2.com`, etc.
|
||||
|
||||
## Specific Values
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
---
|
||||
title: "Troubleshooting"
|
||||
description: "This guide describes and helps users provide information during troubleshooting including sanitization etc"
|
||||
lead: "This guide describes and helps users provide troubleshooting information."
|
||||
date: 2023-05-01T11:30:07+10:00
|
||||
draft: false
|
||||
images: []
|
||||
menu:
|
||||
reference:
|
||||
parent: "guides"
|
||||
weight: 220
|
||||
toc: true
|
||||
aliases:
|
||||
- /r/sanitize
|
||||
- /r/troubleshoot
|
||||
- /r/troubleshooting
|
||||
---
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
See the [Frequently Asked Questions](frequently-asked-questions.md) reference guide for links to frequently asked
|
||||
question documentation.
|
||||
|
||||
## Logs
|
||||
|
||||
It's really important when troubleshooting and even more important when reporting a bug that users provide complete
|
||||
log files. In addition the [log level](../../configuration/miscellaneous/logging.md#level) should always be set to
|
||||
`debug` at minimum, if not `trace`.
|
||||
|
||||
Complete logs means at minimum from the [log severity line](#log-severity-line) until the actual issue occurs. Though
|
||||
more than this may be included at the users discretion.
|
||||
|
||||
### Large Amount of Logs
|
||||
|
||||
In instances where the logs are substantial we will accept truncated logs. There are however some very intentional rules
|
||||
about truncation of logs.
|
||||
|
||||
1. You must show more than 1 minute of logs prior to the issue occurring (i.e. show every log line )
|
||||
2. The level rule still applies.
|
||||
3. You must show:
|
||||
1. The [log severity line](#log-severity-line).
|
||||
2. The [listening line](#listening-line) and the 10 log lines which follow this line.
|
||||
3. The lines between these two lines, which should also include the [starting line](#starting-line).
|
||||
4. No warning or error that is potentially related to the issue should be truncated.
|
||||
|
||||
### Important Log Lines
|
||||
|
||||
The following log lines are important and are referenced by other sections of this document.
|
||||
|
||||
#### Log Severity Line
|
||||
|
||||
The log severity line will have a message which is similar to the following examples:
|
||||
|
||||
- `Log severity set to debug`
|
||||
- `Log severity set to trace`
|
||||
|
||||
#### Starting Line
|
||||
|
||||
The starting line will have a message which is similar to the following examples:
|
||||
|
||||
- `Authelia v4.37.5 is starting`
|
||||
- `Authelia v4.38.0 is starting`
|
||||
- `Authelia untagged-v4.38.0 (master, 50d8b4a) is starting`
|
||||
|
||||
#### Listening Line
|
||||
|
||||
The listening line will have a message which is similar to the following examples:
|
||||
|
||||
- `Listening for non-TLS connections on '0.0.0.0:9091' path '/'`
|
||||
- `Listening for TLS connections on '0.0.0.0:9091' path '/'`
|
||||
- `Listening for non-TLS connections on ':9091' path '/'`
|
||||
- `Listening for non-TLS connections on ':9091' path '/' and '/authelia'`
|
||||
|
||||
## Sanitization
|
||||
|
||||
Some users may wish to hide their domain in files provided during troubleshooting. While this is discouraged, if a user
|
||||
decides to perform this action it's critical for these purposes that you hide your domain in a very specific
|
||||
way. Most editors allow replacing all instances of a value, utilizing this is essential to making troubleshooting
|
||||
possible.
|
||||
|
||||
### General Rules
|
||||
|
||||
1. Only replace the purchased portion of domains:
|
||||
- For example if you have `auth.abc123.com` and `app.abc123.com` they
|
||||
should become `auth.example.com` and `app.example.com`, i.e. replace all instances of `abc123.com` with `example.com`.
|
||||
2. Make sure value replaced is replaced with a unique value:
|
||||
- For example if you replace `abc123.com` with `example.com` DO NOT replace any other value other than `abc123.com` with
|
||||
`example.com`. The same rule applies to IP addresses, usernames, and groups.
|
||||
3. Make sure the value replaced is replaced across logs, configuration, and any references:
|
||||
- For example if you replace `abc123.com` with `example.com` in your configuration, make exactly the same replacement
|
||||
for the log files.
|
||||
4. Make sure this consistency is followed for all communication regarding a single issue.
|
||||
|
||||
### Multiple Domains
|
||||
|
||||
*__Replacement Value:__* `example#.com` (where `#` is a unique number per domain)
|
||||
|
||||
In instances where there are multiple domains it's recommended these domains are replaced with `example1.com`,
|
||||
`example2.com`, etc.
|
||||
Loading…
Reference in New Issue