If you wish to view the script's logging documentation, you can click on this link: [Logging Documentation](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/docs/contrib/bash-log.md).
Below is the documentation for logging and error handling in the OpenIM Go project.
To create a standard set of documentation that is quick to read and easy to understand, we will highlight key information about the `Logger` interface and the `CodeError` interface. This includes the purpose of each interface, key methods, and their use cases. This will help developers quickly grasp how to effectively use logging and error handling within the project.
## Logging (`Logger` Interface)
### Purpose
The `Logger` interface aims to provide the OpenIM project with a unified and flexible logging mechanism, supporting structured logging formats for efficient log management and analysis.
### Key Methods
- **Debug, Info, Warn, Error**
Log messages of different levels to suit various logging needs and scenarios. These methods accept a context (`context.Context`), a message (`string`), and key-value pairs (`...interface{}`), allowing the log to carry rich context information.
- **WithValues**
Append key-value pair information to log messages, returning a new `Logger` instance. This helps in adding consistent context information.
- **WithName**
Set the name of the logger, which helps in identifying the source of the logs.
- **WithCallDepth**
Adjust the call stack depth to accurately identify the source of the log message.
### Use Cases
- Developers should choose the appropriate logging level (such as `Debug`, `Info`, `Warn`, `Error`) based on the importance of the information when logging.
- Use `WithValues` and `WithName` to add richer context information to logs, facilitating subsequent tracking and analysis.
## Error Handling (`CodeError` Interface)
### Purpose
The `CodeError` interface is designed to provide a unified mechanism for error handling and wrapping, making error information more detailed and manageable.
### Key Methods
- **Code**
Return the error code to distinguish between different types of errors.
- **Msg**
Return the error message description to display to the user.
- **Detail**
Return detailed information about the error for further debugging by developers.
- **WithDetail**
Add detailed information to the error, returning a new `CodeError` instance.
- **Is**
Determine whether the current error matches a specified error, supporting a flexible error comparison mechanism.
- **Wrap**
Wrap another error with additional message description, facilitating the tracing of the error's cause.
### Use Cases
- When defining errors with specific codes and messages, use error types that implement the `CodeError` interface.
- Use `WithDetail` to add additional context information to errors for more accurate problem localization.
- Use the `Is` method to judge the type of error for conditional branching.
- Use the `Wrap` method to wrap underlying errors while adding more contextual descriptions.
## Logging Standards and Code Examples
In the OpenIM project, we use the unified logging package `github.com/OpenIMSDK/tools/log` for logging to achieve efficient log management and analysis. This logging package supports structured logging formats, making it easier for developers to handle log information.
We use the `github.com/OpenIMSDK/tools/errs` package for unified error handling and wrapping.
### CodeError Interface and Implementation
The error interface is defined as follows:
```go
type CodeError interface {
Code() int
Msg() string
Detail() string
WithDetail(detail string) CodeError
Is(err error, loose ...bool) bool
Wrap(msg ...string) error
error
}
```
Example code: Creating and using the `CodeError` interface to handle errors.
```go
package main
import (
"fmt"
"github.com/OpenIMSDK/tools/errs"
)
func main() {
err := errs.New(404, "Resource not found")
err = err.WithDetail("
More details")
if e, ok := err.(errs.CodeError); ok {
fmt.Println(e.Code(), e.Msg(), e.Detail())
}
}
```
### Detailed Logging Standards and Code Examples
1.**Print key information at startup**
It is crucial to print entry parameters and key process information at program startup. This helps understand the startup state and configuration of the program.
**Code Example**:
```go
package main
import (
"fmt"
"os"
)
func main() {
fmt.Println("Program startup, version: 1.0.0")
fmt.Printf("Connecting to database: %s\n", os.Getenv("DATABASE_URL"))
}
```
2.**Use `tools/log` and `fmt` for logging**
Logging should be done using a specialized logging library for unified management and formatted log output.
**Code Example**: Logging an info level message with `tools/log`.
```go
package main
import (
"context"
"github.com/OpenIMSDK/tools/log"
)
func main() {
ctx := context.Background()
log.Info(ctx, "Application started successfully")
}
```
3.**Use standard error output for startup failures or critical information**
Critical error messages or program startup failures should be indicated to the user through standard error output.
6.**Handling logs for API RPC calls and non-RPC applications**
For API RPC calls using gRPC, logs at the information level are printed by middleware on the gRPC server side, reducing the need to manually log in each RPC method. For non-RPC applications, it's recommended to manually log key execution paths to track the application's execution flow.
**gRPC Server-Side Logging Middleware:**
In gRPC, `UnaryInterceptor` and `StreamInterceptor` can intercept Unary and Stream type RPC calls, respectively. Here's an example of how to implement a simple Unary RPC logging middleware:
```go
package main
import (
"context"
"google.golang.org/grpc"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
"log"
"time"
)
// unaryServerInterceptor returns a new unary server interceptor that logs each request.
For non-RPC applications, the key is to log at appropriate places in the code to maintain an execution trace. Here's a simple example showing how to log when handling a task:
In both scenarios, appropriate logging can help developers and operators monitor the health of the system, trace the source of issues, and quickly locate and resolve problems. For gRPC logging, using middleware can effectively centralize log management and control. For non-RPC applications, ensuring logs are placed at critical execution points can help understand the program's operational flow and state changes.
### When to Wrap Errors?
1.**Wrap errors generated within the function**
When an error occurs within a function, use `errs.Wrap` to add context information to the original error.
**Code Example**:
```go
func doSomething() error {
// Suppose an error occurs here
err, _ := someFunc()
if err != nil {
return errs.Wrap(err, "doSomething failed")
}
}
```
2.**Wrap errors from system calls or other packages**
When calling external libraries or system functions that return errors, also add context information to wrap the error.
**Code Example**:
```go
func readConfig(file string) error {
_, err := os.ReadFile(file)
if err != nil {
return errs.Wrap(err, "Failed to read config file")
}
return nil
}
```
3.**No need to re-wrap errors for internal module calls**
If an error has been appropriately wrapped with sufficient context information in an internal module call, there's no need to wrap it again.
**Code Example**:
```go
func doSomething() error {
err := doAnotherThing()
if err != nil {
return err
}
return nil
}
```
4.**Ensure comprehensive wrapping of errors with detailed messages**
When wrapping errors, ensure to provide ample context information to make the error more understandable and easier to debug.
**Code Example**:
```go
func connectDatabase() error {
err := db.Connect(config.DatabaseURL)
if err != nil {
return errs.Wrap(err, fmt.Sprintf("Failed to connect to database, URL: %s", config.DatabaseURL))
