smartlog/readme.md

# @push.rocks/smartlog

minimalistic distributed and extensible logging tool

## Install

You can install `@push.rocks/smartlog` using npm:

```sh
npm install @push.rocks/smartlog --save
```

Ensure that you have TypeScript and node.js installed in your development environment, as this module is intended to be used with TypeScript.

## Usage

`@push.rocks/smartlog` is a flexible and extensible logging tool designed to provide a minimalistic yet powerful logging solution across different environments, making it especially useful in distributed systems. This documentation aims to guide you through its capabilities, setup, and how to integrate it seamlessly into your TypeScript projects.

### Creating a Logger Instance

Start by importing `Smartlog` and create a logger instance by providing a context that describes your logging environment:

```typescript
import { Smartlog } from '@push.rocks/smartlog';

const logger = new Smartlog({
  logContext: {
    company: 'My awesome company',
    companyunit: 'my awesome cloud team',
    containerName: 'awesome-container',
    environment: 'kubernetes-production',
    runtime: 'node',
    zone: 'zone x'
  }
});
```

This context enriches your logs with valuable information, making them easier to filter and analyze in a distributed system.

### Logging Messages

Logging is straightforward; you can log messages at various levels such as `info`, `warn`, `error`, `silly`, etc.:

```typescript
logger.log('info', 'This is an info message');
logger.log('error', 'This is an error message with details', { errorCode: 123 });
```

The logging method accepts additional data as the third parameter, allowing you to attach more context to each log message, which is immensely useful for debugging.

### Using the Default Logger

For convenience, `@push.rocks/smartlog` provides a default logger that you can use out of the box:

```typescript
import { defaultLogger } from '@push.rocks/smartlog';

defaultLogger.log('warn', 'This is a warning message using the default logger');
```

This is particularly helpful for simple applications or for initial project setup.

### Extending With Log Destinations

One of the core strengths of `@push.rocks/smartlog` is its ability to work with multiple log destinations, enabling you to log messages not just to the console but also to external logging services or custom destinations.

To add a log destination, you create a class that implements the `ILogDestination` interface and then add it to the logger:

```typescript
import { Smartlog, ILogDestination } from '@push.rocks/smartlog';

class MyCustomLogDestination implements ILogDestination {
  async handleLog(logPackage) {
    // Implement your custom logging logic here
    console.log(`Custom log: ${logPackage.message}`);
  }
}

const logger = new Smartlog({ logContext: { /* your context */ } });
logger.addLogDestination(new MyCustomLogDestination());
```

After adding your custom log destination(s), every log message sent through `Smartlog` will also be routed to them according to their implementation.

### Integration with Logging Services

`@push.rocks/smartlog` is designed to be extensible; you can integrate it with various logging services like Scalyr, Elasticsearch, LogDNA, etc., by developing or using existing log destinations conforming to those services.

Check the npm registry or GitHub for community-contributed log destinations that can seamlessly integrate `@push.rocks/smartlog` into your preferred logging infrastructure.

### Advanced Usage

- **Log Groups**: You can use log groups to associate related log messages, which is especially handy for tracking logs across distributed systems.
- **Custom Log Levels**: Beyond the standard log levels, you can define custom log levels that suit your project needs.
- **Dynamic Log Contexts**: The log context can be dynamically adjusted to reflect different stages or aspects of your application logic.

### Conclusion

`@push.rocks/smartlog` empowers you to implement a robust logging solution tailored to your needs with minimal effort. Its design promotes clarity, flexibility, and integration ease, making it an excellent choice for projects of any scale.

Remember to refer to the official documentation and the type definitions for detailed information on all available methods and configurations. Happy logging!

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.