sigs.k8s.io/cluster-api@v1.7.1/cmd/clusterctl/log/doc.go (about)

     1  /*
     2  Copyright 2020 The Kubernetes Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  /*
    18  Package log mirrors the controller runtime approach to logging, by defining a global logger
    19  that defaults to NullLogger.
    20  
    21  You can set a custom logger by calling log.SetLogger.
    22  
    23  NewLogger returns a clusterctl friendly logr.Logger derived from
    24  https://git.k8s.io/klog/klogr/klogr.go.
    25  
    26  The logger is designed to print logs to stdout with a formatting that is easy to read for users
    27  but also simple to parse for identifying specific values.
    28  
    29  Note: the clusterctl library also support usage of other loggers as long as they conform to the github.com/go-logr/logr.Logger interface.
    30  
    31  Following logging conventions are used in clusterctl library:
    32  
    33  Message:
    34  
    35  All messages should start with a capital letter.
    36  
    37  Log level:
    38  
    39  Use Level 0 (the default, if you don't specify a level) for the most important user feedback only, e.g.
    40  - reporting command progress for long running actions
    41  - reporting command results when required
    42  
    43  Use logging Levels 1 providing more info about the command's internal workflow.
    44  
    45  Use logging Levels 5 for providing all the information required for debug purposes/problem investigation.
    46  
    47  Logging WithValues:
    48  
    49  Logging WithValues should be preferred to embedding values into log messages because it allows
    50  machine readability.
    51  
    52  Variables name should start with a capital letter.
    53  
    54  Logging WithNames:
    55  
    56  Logging WithNames should be used carefully.
    57  Please consider that practices like prefixing the logs with something indicating which part of code
    58  is generating the log entry might be useful for developers, but it can create confusion for
    59  the end users because it increases the verbosity without providing information the user can understand/take benefit from.
    60  
    61  Logging errors:
    62  
    63  A proper error management should always be preferred to the usage of log.Error.
    64  */
    65  package log