dotnet/src/webdriver/Internal/Logging/ILogContext.cs

// <copyright file="ILogContext.cs" company="Selenium Committers">
// Licensed to the Software Freedom Conservancy (SFC) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The SFC licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.
// </copyright>

using System;

namespace OpenQA.Selenium.Internal.Logging;

/// <summary>
/// Represents a logging context that provides methods for creating sub-contexts, retrieving loggers, emitting log messages, and configuring minimum log levels.
/// </summary>
public interface ILogContext : IDisposable
{
    /// <summary>
    /// Creates a new logging context.
    /// </summary>
    /// <returns>A new instance of <see cref="ILogContext"/>.</returns>
    ILogContext CreateContext();

    /// <summary>
    /// Creates a new logging context with the specified minimum log level.
    /// </summary>
    /// <param name="minimumLevel">The minimum log level for the new context.</param>
    /// <returns>A new instance of <see cref="ILogContext"/> with the specified minimum log level.</returns>
    ILogContext CreateContext(LogEventLevel minimumLevel);

    /// <summary>
    /// Gets a logger for the specified type.
    /// </summary>
    /// <typeparam name="T">The type for which to retrieve the logger.</typeparam>
    /// <returns>An instance of <see cref="ILogger"/> for the specified type.</returns>
    internal ILogger GetLogger<T>();

    /// <summary>
    /// Gets a logger for the specified type.
    /// </summary>
    /// <param name="type">The type for which to retrieve the logger.</param>
    /// <returns>An instance of <see cref="ILogger"/> for the specified type.</returns>
    internal ILogger GetLogger(Type type);

    /// <summary>
    /// Checks whether logs emitting is enabled for a logger and a log event level.
    /// </summary>
    /// <param name="logger">The specified logger instance to be checked.</param>
    /// <param name="level">The specified log event level to be checked.</param>
    /// <returns><see langword="true"/> if log messages emitting is enabled for the specified logger and log event level, otherwise <see langword="false"/>.</returns>
    internal bool IsEnabled(ILogger logger, LogEventLevel level);

    /// <summary>
    /// Emits a log message using the specified logger, log level, and message.
    /// </summary>
    /// <param name="logger">The logger to emit the log message.</param>
    /// <param name="timestamp">The timestamp of the log event.</param>
    /// <param name="level">The log level of the message.</param>
    /// <param name="message">The log message.</param>
    internal void EmitMessage(ILogger logger, DateTimeOffset timestamp, LogEventLevel level, string message);

    /// <summary>
    /// Sets the minimum log level for the current context.
    /// </summary>
    /// <param name="level">The minimum log level.</param>
    /// <returns>The current instance of <see cref="ILogContext"/> with the minimum log level set.</returns>
    ILogContext SetLevel(LogEventLevel level);

    /// <summary>
    /// Sets the minimum log level for the specified type in the current context.
    /// </summary>
    /// <param name="issuer">The type for which to set the minimum log level.</param>
    /// <param name="level">The minimum log level.</param>
    /// <returns>The current instance of <see cref="ILogContext"/> with the minimum log level set for the specified type.</returns>
    ILogContext SetLevel(Type issuer, LogEventLevel level);

    /// <summary>
    /// Sets the truncation length for log messages in the current context.
    /// </summary>
    /// <param name="length">The maximum length of log messages before truncation occurs. Pass <see langword="null"/> to disable truncation.</param>
    /// <returns>The current instance of <see cref="ILogContext"/> with the truncation length set.</returns>
    ILogContext WithTruncation(int? length);

    /// <summary>
    /// Gets a list of log handlers.
    /// </summary>
    ILogHandlerList Handlers { get; }
}