# log4a

**Repository Path**: ericple/log4a

## Basic Information

- **Project Name**: log4a
- **Description**: 轻量、易集成、易使用，有时甚至可以不需写代码的HarmonyOS log系统，灵感来自log4j。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://peercat.cn/log4a/
- **GVP Project**: No

## Statistics

- **Stars**: 61
- **Forks**: 21
- **Created**: 2024-04-20
- **Last Updated**: 2025-09-13

## Categories & Tags

**Categories**: logging, harmonyos-devtools

**Tags**: OpenHarmony组件, HarmonyOS组件

## README

# Log4a

Lightweight, easy to integrate, easy to use, and sometimes even code free HarmonyOS log system, inspired by log4j.

## Installation

- Use `ohpm` to install `@pie/log4a`

```bash
ohpm install @pie/log4a
```

For other installation, please refer to the [this article](https://ohpm.openharmony.cn/#/cn/help/downloadandinstall).

## Use

### Common process

- Get logger

Use `LogManager.getLogger(context)` to get the available Logger for the current object. The method is simply passed in '
this'.

```typescript
import { LogManager, Logger } from '@pie/log4a';

class LogTestClass {
  private logger: Logger = LogManager.getLogger(this);
  //... Other code
}
```

- Use logger

After obtaining the logger, start printing logs:

```typescript
import { LogManager, Logger } from '@pie/log4a';

class LogTestClass {
  private logger: Logger = LogManager.getLogger(this);

  add(a: number, b: number) {
    this.logger.info('calculating {} + {}', a, b);
    return a + b;
  }
}

const adder = new LogTestClass;
adder.add(1, 2);
```

The above code, when executed, prints out a log that looks like this

```bash
[INFO] 2024-04-19 23:32:54.746 [LogTestClass:1] calculating 1 + 2
```

The log generated by log4a contains the following information:

- Log level
- Log time
- Log source
- Log content

> ### Log source
> When logger belongs to a class or struct:
>
> For non-static Loggers, the log source is the name of the class or struct
>
> For the static logger, the log source is Function
> ```typescript
> import { LogManager, Logger } from '@pie/log4a';
> class StaticLogger {
>   private static logger: Logger = LogManager.getLogger(this);
>   static hello() {
>     StaticLogger.logger.info("Hello from static logger");
>   }
> }
> ```
> This code will print:
> ```bash
> [INFO] 2024-04-19 23:32:54.746 [Function:1] Hello from static logger
> ```

### Tracker

log4a designed the tracker, which can help you track the function running parameters, function running results, template
string construction.

Available trackers:

- `@TraceEntry` : Used to track function running parameters, as shown in the following example:

```typescript
import { TraceEntry } from '@pie/log4a';

class TestClass {
  @TraceEntry
  add(a: number, b: number): number {
    return a + b;
  }
}

const t = new TestClass;
t.add(1, 2);
```

Although no log code is written, this code will still show the following log after running:

```bash
[TRACE] 2024-04-20 00:19:43.24 [TestClass:1] Method: [add] called with arguments [1,2]
```

This means that a function decorated with @TraceEntry will be tracked, and every time it is called, log4a will print a
log containing the name of the function and the arguments passed in for the call.

- `@TraceExit` : Used to trace the result of a function, as shown in the following example:

```typescript
import { TraceExit } from '@pie/log4a';

class TestClass {
  @TraceExit
  add(a: number, b: number): number {
    return a + b;
  }
}

const t = new TestClass;
t.add(1, 2);
```

Although no log code is written, this code will still show the following log after running:

```bash
[TRACE] 2024-04-20 00:19:43.24 [TestClass:1] Method: [add] exited with result: 3
```

This means that a function decorated with @TraceExit will be tracked, and every time it is called, log4a will print a
log containing the name of the function and the result returned by the call.

- `TracedStr` : Used to trace the construction of a string template, as shown in the following example:

```typescript
import { TracedStr } from '@pie/log4a';

class TestClass {
  param1: string = 'param1';
  param2: string = 'param2';
  str: string = TracedStr`build with ${this.param1} and ${this.param2}`;
}

const t = new TestClass;
```

Although no log code is written, this code will still show the following log after running:

```bash
[INFO] 2024-04-20 00:27:51.989 [Anonymous:1] built with format: ["build with "," and ","] and args: ["param1","param2"] (Anonymous)
```

Note that TracedStr is a tag, not a decorator, so the '@' lead is not required.

- `MarkedTracedStr` : To make it easier for users to track specific template string builds, use this tag and pass in a
  string as a tag

```typescript
import { MarkedTracedStr } from '@pie/log4a';

class TestClass {
  param1: string = 'param1';
  param2: string = 'param2';
  str: string = MarkedTracedStr("StrBuilder")`build with ${this.param1} and ${this.param2}`;
}

const t = new TestClass;
```

Although no log code is written, this code will still show the following log after running:

```bash
[INFO] 2024-04-20 00:33:31.793 [Anonymous:2] built with format: ["build with "," and ","] and args: ["param1","param2"] (StrBuilder)
```

Note that 'MarkedTracedStr' is a function, not a tag, and requires passing in an argument.

### Constraints and limitations

DevEco Studio NEXT Developer Preview 2 (4.1.3.700), SDK: API11 (4.1.0(11))
> This library theoretically supports all API versions

### Contribute code

- [Submit Issue](https://gitee.com/ericple/log4a/issues/new)
- [Create A Pull Request](https://gitee.com/ericple/ohos-weather/pull/new)

### Open source protocol

This project uses [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt).