# est-spi-observability

**Repository Path**: est-spi/observability

## Basic Information

- **Project Name**: est-spi-observability
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EST SPI Observability

[English Version](README.en.md)

## EST SPI 可观测性模块

est-spi-observability 是 EST SPI 框架的可观测性模块，提供日志、指标和分布式追踪功能。

### 核心功能

#### Logger - 日志接口
定义日志接口，支持TRACE、DEBUG、INFO、WARN、ERROR级别。

#### Level - 日志级别枚举
定义日志级别：TRACE、DEBUG、INFO、WARN、ERROR。

#### SimpleLogger - 简单日志实现
基于控制台的简单日志实现。

#### Metrics - 指标接口
定义指标接口，支持计数器、仪表盘、直方图和计时器。

#### SimpleMetrics - 简单指标实现
基于内存的简单指标实现。

#### Tracer - 追踪接口
定义分布式追踪接口，支持创建和管理Span。

#### SimpleTracer - 简单追踪实现
基于内存的简单追踪实现。

#### ObservationContext - 观测上下文接口
定义观测上下文接口，组合Logger、Metrics和Tracer。

#### DefaultObservationContext - 默认观测上下文实现
观测上下文的默认实现。

### 快速开始

#### 创建日志器

```java
import ltd.idcu.est.spi.observability.Logger;
import ltd.idcu.est.spi.observability.SimpleLogger;
import ltd.idcu.est.spi.observability.Level;

public class Example {
    public static void main(String[] args) {
        Logger logger = new SimpleLogger("MyLogger", Level.DEBUG);
        
        logger.trace("Trace message");
        logger.debug("Debug message");
        logger.info("Info message");
        logger.warn("Warn message");
        logger.error("Error message");
    }
}
```

#### 使用参数化日志

```java
import ltd.idcu.est.spi.observability.Logger;

public class Example {
    public static void main(String[] args) {
        Logger logger = ...;
        
        logger.info("User {} logged in from {}", "Alice", "192.168.1.1");
        logger.debug("Processing {} records", 100);
    }
}
```

#### 动态设置日志级别

```java
import ltd.idcu.est.spi.observability.Logger;
import ltd.idcu.est.spi.observability.Level;

public class Example {
    public static void main(String[] args) {
        Logger logger = ...;
        
        logger.setLevel(Level.DEBUG);
        assertTrue(logger.isDebugEnabled());
        
        logger.setLevel(Level.INFO);
        assertFalse(logger.isDebugEnabled());
    }
}
```

#### 使用指标

```java
import ltd.idcu.est.spi.observability.Metrics;
import ltd.idcu.est.spi.observability.SimpleMetrics;

public class Example {
    public static void main(String[] args) {
        Metrics metrics = new SimpleMetrics();
        
        metrics.counter("requests.total", 1);
        metrics.gauge("system.load", 0.75);
        metrics.histogram("response.time", 150.5);
        metrics.timer("operation.duration", 250);
        
        System.out.println("Counter: " + ((SimpleMetrics) metrics).getCounter("requests.total"));
    }
}
```

#### 使用计时器

```java
import ltd.idcu.est.spi.observability.Metrics;

public class Example {
    public static void main(String[] args) {
        Metrics metrics = ...;
        
        String result = metrics.time("database.query", () -> {
            Thread.sleep(100);
            return "query result";
        });
        
        metrics.time("file.process", () -> {
            Thread.sleep(50);
        });
    }
}
```

#### 使用追踪

```java
import ltd.idcu.est.spi.observability.Tracer;
import ltd.idcu.est.spi.observability.SimpleTracer;

public class Example {
    public static void main(String[] args) {
        Tracer tracer = new SimpleTracer();
        
        Tracer.Span parentSpan = tracer.startSpan("parent.operation");
        parentSpan.setTag("service", "my-service");
        
        parentSpan.log("Starting operation");
        
        Tracer.Span childSpan = tracer.startSpan("child.operation", parentSpan);
        childSpan.log("Child operation started");
        childSpan.finish();
        
        parentSpan.log("Operation completed");
        parentSpan.finish();
        
        System.out.println("Parent duration: " + parentSpan.getDurationMs() + "ms");
    }
}
```

#### 使用观测上下文

```java
import ltd.idcu.est.spi.observability.ObservationContext;
import ltd.idcu.est.spi.observability.DefaultObservationContext;

public class Example {
    public static void main(String[] args) {
        ObservationContext context = new DefaultObservationContext("MyService");
        
        context.setAttribute("requestId", "12345");
        context.setAttribute("userId", "user123");
        
        context.getLogger().info("Processing request");
        
        context.getMetrics().counter("requests", 1);
        
        String result = ((DefaultObservationContext) context).observe("process.request", () -> {
            context.getLogger().debug("Inside observation");
            return "result";
        });
    }
}
```

#### 自定义观测上下文组件

```java
import ltd.idcu.est.spi.observability.ObservationContext;
import ltd.idcu.est.spi.observability.DefaultObservationContext;
import ltd.idcu.est.spi.observability.Logger;
import ltd.idcu.est.spi.observability.SimpleLogger;
import ltd.idcu.est.spi.observability.Level;

public class Example {
    public static void main(String[] args) {
        ObservationContext context = new DefaultObservationContext("MyService");
        
        Logger customLogger = new SimpleLogger("CustomLogger", Level.TRACE);
        context.setLogger(customLogger);
        
        context.getLogger().trace("This trace message will be logged");
    }
}
```

### Maven 依赖

```xml
<dependency>
    <groupId>ltd.idcu.est.spi</groupId>
    <artifactId>est-spi-observability</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 许可证

MIT License