sap-btp-cloud-logging-client
Version:
SAP BTP Cloud Logging client for Node.js applications
177 lines (157 loc) • 6.49 kB
Markdown
# SAP BTP Cloud Logging Client
[](https://www.npmjs.com/package/sap-btp-cloud-logging-client) [](https://www.npmjs.com/package/sap-btp-cloud-logging-client)
A Package support using cloud logging multiple-sub accounts with 1 Cloud Logging instance
Example: Your System Landscape with 3 global account (2 CPEA, 1 PAYG)
```
├── Global CPEA Subcribe
│ ├── Sub Account A Subcribed Cloud Logging
│ ├── Sub Account B using Cloud Logging via sap-btp-cloud-logging-client
├── Global CPEA using/
│ └── Sub Account C using Cloud Logging via sap-btp-cloud-logging-client
├── Global PAYG/
│ └── Sub Account D using Cloud Logging via sap-btp-cloud-logging-client
```
## Project Structure
```
sap-btp-cloud-logging-client/
├── package.json
├── README.md
├── LICENSE
├── index.js
├── lib/
│ ├── CloudLoggingService.js
│ ├── LogFormatter.js
│ └── ConfigManager.js
├── types/
│ └── index.d.ts
├── examples/
│ ├── basic-usage.js
│ ├── express-middleware.js
│ └── advanced-usage.js
└── test/
└── CloudLoggingService.test.js
```
## Usage
### Install package
```
npm install sap-btp-cloud-logging-client
```
### Env config
All required config bellow can get from Service: Cloud Logging instance Service Keys
- v1.0.0 it's support only this way
```
# Required
BTP_LOGGING_INGEST_ENDPOINT=https://ingest-sf-xxx.cls-16.cloud.logs.services.eu10.hana.ondemand.com
BTP_LOGGING_USERNAME=your-ignest-username
BTP_LOGGING_PASSWORD=your-ingest-password
# Optional
BTP_SUBACCOUNT_ID=subaccount-id #to determine the logs source
BTP_APPLICATION_NAME=your-app-name #it's based on application
BTP_LOG_LEVEL=INFO
BTP_LOGGING_MAX_RETRIES=3
BTP_LOGGING_TIMEOUT=5000
```
- from v1.0.1 support new way using json from service key JSON of Cloud Logging (still auth by basic not mtls way -> then you can remove ```server-ca,ingest-mtls-key,ingest-mtls-cert,client-ca``` we no need it any more just add this for lazy set multiple env prop)
Get it from ```SubAccount (Subcribtion Cloug Logging) -> Instance Cloud Logging -> Service Keys (if not exist create new one)```
BTP_LOGGING_SRV_KEY_CRED = {copy all json from Cloud Logging Service Key}
Example: ```BTP_LOGGING_SRV_KEY_CRED ='<json content copy from service key>'```
```
BTP_LOGGING_SRV_KEY_CRED ='{
"client-ca": "<sensitive>",
"dashboards-endpoint": "dashboards-sf-61111e58-2a9a-4790-9baf-efe56ec2c871.cls-16.cloud.logs.services.eu10.hana.ondemand.com",
"dashboards-password": "<sensitive>",
"dashboards-username": "<sensitive>",
"ingest-endpoint": "ingest-sf-61111e58-2a9a-4790-9baf-efe56ec2c871.cls-16.cloud.logs.services.eu10.hana.ondemand.com",
"ingest-mtls-cert": "",
"ingest-mtls-endpoint": "ingest-mtls-sf-61111e58-2a9a-4790-9baf-efe56ec2c871.cls-16.cloud.logs.services.eu10.hana.ondemand.com",
"ingest-mtls-key": "",
"ingest-password": "<sensitive>",
"ingest-username": "vMSeXiYcYF",
"server-ca":"<sensitive>"
}'
```
### Auth & post log
We'll use username, password from service key for ```basic auth``` for ```mtls``` way seem the key valid max only ```180 days``` we've to create a feature auto create/get new key...etc it complex even we've env ```BTP_LOGGING_SRV_AUTH_TYPE='basic';//allow: basic,mtls``` but not recommend using ```mtls``` this time
### Instance Specify Config
```
const logger = createLogger({
ingestEndpoint: 'https://ingest-sf-xxx.cls-16.cloud.logs.services.eu10.hana.ondemand.com',
username: 'your-username',
password: 'your-password',
applicationName: 'my-app',
subaccountId: 'subaccount-b',
environment: 'production'
});
```
### Implementation
#### Basic
- Javascript
```
const { createLogger } = require('sap-btp-cloud-logging-client');
const logger = createLogger();
logger.info('Hello from BTP Cloud Logging!');
```
- Typescript
```
import { createLogger, middleware as loggingMiddleware } from 'sap-btp-cloud-logging-client';
const logger = createLogger();
logger.info('Hello from BTP Cloud Logging!');
```
or can create a common class for using
```
import { createLogger } from 'sap-btp-cloud-logging-client';
export function getCloudLogger(): any {
try {
//Leo: using default instance with env value maintenance
const btpCloudLogger = createLogger();
if(!btpCloudLogger){
throw new Error(`Can't get BTP Cloud Logging Client instance`);
}
return btpCloudLogger;
} catch (error) {
console.log(`get BTP Cloud Logging Client instance error: ${error.message ?? 'N\A'}`);
throw new Error(`Can't get BTP Cloud Logging Client instance`);
}
}
```
#### Add metadata dynamic property
```
const sampleMetadata = {
source:"S4",
source_system:"S4H_DEMO",
payload: {
user:"leo"
}
};
logger.info(`New Supplier Created`,sampleMetadata);
```
Result
#### Logs Batch
```
async function batchLogging() {
const entries = [
{ level: 'INFO', message: 'Batch entry 1', metadata: { batch: 1 } },
{ level: 'INFO', message: 'Batch entry 2', metadata: { batch: 2 } },
{ level: 'WARN', message: 'Batch entry 3', metadata: { batch: 3 } }
];
await logger.logBatch(entries);
}
```
### Dashboard & Discovery Logs
#### Cloud Logging Open Search Dashboard
- The url/ credential to access Dashboard inside Service Key you will see
```
"dashboards-endpoint": "dashboards-sf-61111e58-2a9a-4790-9baf-efe56ec2c871.cls-16.cloud.logs.services.eu10.hana.ondemand.com",
"dashboards-password": "<sensitive>",
"dashboards-username": "<sensitive>",
```
Using browser to visit url: ```dashboards-endpoint``` and cred (username, password) above
- Discovery Logs: from the dashboard click to Discovery menu on the left side
Then you should filter by ```logs-json-*```
here you can filter data by sub account, application...etc
## Contributors
We want to make contributing to this project as easy and transparent as possible. So, just simple do the change then create PR