add-observability-express

分类: 运维与交付 | 上传者: dmorsoletociandt | 下载: 0 | 版本: v1.0（最新）
Add observability instrumentation to Express.js services using sanitizeObjectToString and getLogger from @digital-platform/express-observability-helper. Only works on Express projects (not NestJS).
更新日志: Source: GitHub https://github.com/dmorsoletociandt/claude-skills
目录结构

当前层级: add-observability-express/
📄 SKILL.md 13.5 KB
SKILL.md

---
name: add-observability-express
description: Add observability instrumentation to Express.js services using sanitizeObjectToString and getLogger from @digital-platform/express-observability-helper. Only works on Express projects (not NestJS).
disable-model-invocation: true
argument-hint: "[file, directory, or leave empty for full project]"
allowed-tools: Read, Grep, Glob, Edit, Bash
---

## Pre-condition: verify this is an Express project (not NestJS)

Before doing anything else, check whether this is an Express project by looking for `express` in `package.json` and confirming `@nestjs/core` is **not** present.

Run: `grep "\"express\"" package.json`
Run: `grep "@nestjs/core" package.json 2>/dev/null`

- If `express` exists and `@nestjs/core` does **not** → proceed normally.
- If `@nestjs/core` is found → stop immediately and respond:
  > "This skill only works on Express projects. Use `add-observability-nest` for NestJS."
- If `express` is not found → stop immediately and respond:
  > "This skill only works on Express projects. `express` was not found in `package.json`."

---

## Target

Apply observability to: **$ARGUMENTS**

- If `$ARGUMENTS` is empty → apply to the entire project (all files under `src/`).
- If `$ARGUMENTS` is a file path → apply only to that file.
- If `$ARGUMENTS` is a directory → apply to all relevant files inside it.

---

## Instructions

Follow every rule in the guide below exactly. Do not skip any step.

---

# Observability Guide — `@digital-platform/express-observability-helper`

## 1. Bootstrap (`server.ts` / `app.ts` / `index.ts`)

Call `initializeObservability` **before** `express()` middlewares are registered. Then apply `createClassCodeMiddleware`, `requestBodyLogger`, `responseBodyLogger`, and `createErrorLogger` as shown:

```typescript
import path from 'path'
import {
  requestBodyLogger,
  responseBodyLogger,
  createErrorLogger,
  createClassCodeMiddleware,
  initializeObservability,
} from '@digital-platform/express-observability-helper'

const { version, name } = require(path.join(process.cwd(), 'package.json'))

class App {
  private express: express.Express

  public async init() {
    this.express = express()

    initializeObservability({
      serviceName: process.env.APP_NAME ?? name,
      version,
      environment: process.env.NODE_ENV ?? 'development',
      tracing: { enabled: true },
      metrics: { enabled: true },
      logging: { enabled: true, level: 'info' },
    })

    this.config()
    this.middlewares()
    this.observabilityMiddlewares() // must come after basic middlewares
    await this.routes()
    this.exception()
  }

  observabilityMiddlewares() {
    this.express.use(createClassCodeMiddleware())
    this.express.use(requestBodyLogger)
    this.express.use(responseBodyLogger)
  }

  exception() {
    // createErrorLogger MUST be the first error middleware, before the custom handler
    this.express.use(
      createErrorLogger({
        ignorePaths: ['/health', '/metrics'],
        sendResponse: false, // delegate response to the next error handler
      })
    )

    this.express.use(async (err, req, res, next) => {
      // ... project-specific error handler
    })
  }
}
```

> **Order matters:**
> 1. `initializeObservability` — called once before any middleware
> 2. `createClassCodeMiddleware` → `requestBodyLogger` → `responseBodyLogger` — applied in `observabilityMiddlewares()`
> 3. `createErrorLogger` — **first** error middleware in `exception()`, before the custom error handler

---

## 2. Logger in every class

In **every** class (service, controller, provider, repository) that makes external calls, declare the logger using `getLogger` from the lib:

```typescript
import {
  getLogger,
  sanitizeObjectToString,
} from '@digital-platform/express-observability-helper'

export class MyService {
  private readonly logger = getLogger()
  // ...
}
```

**For classes that receive dependencies via constructor injection**, accept a `logger` parameter typed against a local `Logger` interface and assign it. The caller passes `new WinstonLogger()` (or equivalent):

```typescript
import { Logger } from '../../log' // local Logger interface
import { sanitizeObjectToString } from '@digital-platform/express-observability-helper'

export class MyExternalService {
  private readonly logger: Logger

  constructor(logger: Logger) {
    this.logger = logger
  }
}
```

> Choose the approach that fits the class:
> - Standalone class (not injected) → use `getLogger()` directly.
> - Class instantiated externally (e.g. `new MyService(logger)`) → accept `logger` via constructor.

---

## 3. Where to add logs

Add logs in **every method that makes an external call**. "External call" means:
- HTTP requests (`axios`, `fetch`, `HttpService`, `AxiosInstance`)
- Auth token requests (SSO, OAuth, ms-login)
- External message broker publish calls (Kafka producers sending to external topics)

Do **not** add logs inside:
- TypeORM/Sequelize/Mongoose repository method calls (internal DB — adds noise without value)
- In-memory cache reads/writes
- Pure helper/utility functions with no I/O

---

## 4. Log format — before the call (Request)

Log **immediately before** the external call with relevant non-sensitive context:

```typescript
this.logger.log(
  sanitizeObjectToString({
    message: '[ClassName.methodName] Request - description',
    param1,
    param2,
  })
)
```

Choose context parameters carefully:
- IDs, codes, counts, statuses, dates, platform names — useful for tracing
- **Never** include passwords, tokens, or full PII payloads
- `sanitizeObjectToString` handles sanitization, but be intentional about what you pass

---

## 5. Log format — after the call (Response)

Log **immediately after** awaiting the result:

```typescript
this.logger.log(
  sanitizeObjectToString({
    message: '[ClassName.methodName] Response - description',
    result: response.data,
  })
)
```

When the result is a collection, prefer logging the count:

```typescript
this.logger.log(
  sanitizeObjectToString({
    message: '[ClassName.methodName] Response - description',
    count: response.data?.length ?? 0,
  })
)
```

---

## 6. Log format — on error (Error)

Inside `catch` blocks, replace `console.log`/`console.error` with:

```typescript
this.logger.error(
  sanitizeObjectToString({
    message: '[ClassName.methodName] Error - description',
    error: error?.response?.data ?? error?.message,
  })
)
```

> Keep any existing `throw` or re-throw after the error log. Do **not** swallow errors that were previously thrown.

---

## 7. Replacing deprecated `sanitizeLogEntry`

If the codebase uses `sanitizeLogEntry` from the same lib, replace **all occurrences** with `sanitizeObjectToString`. They are functionally equivalent; `sanitizeLogEntry` is the deprecated name.

```bash
# Find all occurrences
grep -rl "sanitizeLogEntry" src/

# Replace (macOS)
sed -i '' 's/sanitizeLogEntry/sanitizeObjectToString/g' <files>

# Replace (Linux)
sed -i 's/sanitizeLogEntry/sanitizeObjectToString/g' <files>
```

---

## 8. Complete example — HTTP External Service (class with injected logger)

```typescript
import axios from 'axios'
import { sanitizeObjectToString } from '@digital-platform/express-observability-helper'
import { Logger } from '../../log'

export class CancelExternalService {
  private baseHttp = axios.create({
    baseURL: process.env.CANCEL_SERVICE_API,
  })
  private readonly logger: Logger

  constructor(logger: Logger) {
    this.logger = logger
  }

  async sendAppointmentToCancelService({ externalId, platform, appName }) {
    try {
      this.logger.log(
        sanitizeObjectToString({
          message: '[CancelExternalService.sendAppointmentToCancelService] Request - sending to Cancel-Service',
          externalId,
          platform,
          appName,
        })
      )

      await this.baseHttp.delete(`cancel/${externalId}/${platform}`, {
        headers: { 'x-app-name': appName },
      })

      this.logger.log(
        sanitizeObjectToString({
          message: '[CancelExternalService.sendAppointmentToCancelService] Response - sent successfully',
          externalId,
          platform,
        })
      )
    } catch (error) {
      this.logger.error(
        sanitizeObjectToString({
          message: '[CancelExternalService.sendAppointmentToCancelService] Error - failed to send',
          externalId,
          platform,
          error: error?.response?.data ?? error?.message,
        })
      )
      throw error
    }
  }
}
```

---

## 9. Complete example — HTTP Utility (standalone functions with getLogger)

```typescript
import axios from 'axios'
import {
  getLogger,
  sanitizeObjectToString,
} from '@digital-platform/express-observability-helper'

const logger = getLogger()

export const createSession = async ({ name, document, clientName }: CreateSessionParams) => {
  try {
    logger.log(
      sanitizeObjectToString({
        message: '[vonageBackendUtils.createSession] Request - creating Vonage session',
        document,
        clientName,
      })
    )

    const { data } = await axios.post(`${getVonageUrl()}/newSession`, { name, document })

    logger.log(
      sanitizeObjectToString({
        message: '[vonageBackendUtils.createSession] Response - session created',
        sessionId: data.session,
      })
    )

    return data.session
  } catch (error) {
    logger.error(
      sanitizeObjectToString({
        message: '[vonageBackendUtils.createSession] Error - failed to create session',
        error: error?.response?.data ?? error?.message,
      })
    )
    throw new Error('Failed to create vonage session')
  }
}
```

---

## 10. Complete example — Auth Provider (SSO / ms-login)

```typescript
import axios from 'axios'
import {
  getLogger,
  sanitizeObjectToString,
} from '@digital-platform/express-observability-helper'

const logger = getLogger()

export class MsLoginV1 {
  static async auth() {
    try {
      // cache check (no log needed — internal operation)
      const cachedToken = await findTokenOnRedis('token:ms-login:v1')
      const isExpired = isExpiredToken(cachedToken)
      if (!isExpired && cachedToken) return cachedToken

      logger.log(
        sanitizeObjectToString({
          message: '[MsLoginV1.auth] Request - authenticating on ms-login v1',
        })
      )

      const { data } = await axios.post(`${process.env.SERVICO_LOGIN}/sessions`, {
        login: process.env.MS_LOGIN_V1_USERNAME,
        senha: process.env.MS_LOGIN_V1_PASSWORD,
      })

      logger.log(
        sanitizeObjectToString({
          message: '[MsLoginV1.auth] Response - token obtained successfully',
        })
      )

      await saveTokenOnCache('token:ms-login:v1', data.token)
      return data.token
    } catch (error) {
      logger.error(
        sanitizeObjectToString({
          message: '[MsLoginV1.auth] Error - authentication failed',
          error: error?.response?.data ?? error?.message,
        })
      )
      throw new Error('Failed to auth on ms login v1')
    }
  }
}
```

> **Note on auth methods:** Never log the credentials themselves (`login`, `senha`, `password`, `token`). Log only the outcome (success/failure) and non-sensitive context like the service name or realm.

---

## 11. Step-by-step execution checklist

When applying this to a repository, follow this order:

1. **Find all files with external HTTP calls:**
   ```bash
   grep -rl "axios\.\|\.get(\|\.post(\|\.put(\|\.patch(\|\.delete(" src/
   ```

2. **Find files already using the lib** (to understand what's already done):
   ```bash
   grep -rl "express-observability-helper" src/
   ```

3. **Replace `sanitizeLogEntry` → `sanitizeObjectToString`** across the whole repo (step 7 above).

4. **Update `server.ts` / `app.ts`** with `initializeObservability`, `createClassCodeMiddleware`, `requestBodyLogger`, `responseBodyLogger`, and `createErrorLogger` (step 1 above).

5. **For each HTTP service/provider/utility file** that lacks `getLogger` or logger injection:
   - Determine the logger pattern: `getLogger()` for standalone, constructor injection for instantiated classes
   - Add the import
   - Add logger declaration
   - Add Request log before each HTTP call
   - Add Response log after each HTTP call
   - Add Error log in each catch block, replacing `console.log`/`console.error`

6. **Verify no duplication:** each log message must appear exactly once. Do not keep `console.log` and `logger.log` for the same event.

---

## 12. Rules summary

| Rule | Do | Don't |
|---|---|---|
| Sanitization function | `sanitizeObjectToString({ message, ...context })` | Use deprecated `sanitizeLogEntry` |
| Logger — standalone class | `private readonly logger = getLogger()` | Instantiate `new WinstonLogger()` inside the class |
| Logger — injected class | Accept `logger: Logger` via constructor | Create a new logger instance internally |
| Log placement | Immediately before and after the HTTP call | Inside axios interceptors or deep inside utility chains |
| Error logging | `this.logger.error(sanitizeObjectToString({...}))` in catch | `console.log` / `console.error` |
| Auth credentials | Log only outcome (success/failure) | Log passwords, tokens, or credentials |
| DB/ORM calls | Skip — no logs needed | Add logs to Sequelize/TypeORM/Mongoose methods |
| Bootstrap order | `initializeObservability` first, then middlewares | Call after `express()` middlewares |
| `createErrorLogger` position | First error middleware in `exception()` | After the custom error handler |
| Deprecated function | Use `sanitizeObjectToString` | Use `sanitizeLogEntry` |
| Collections | Log `count` instead of full array | Log entire response arrays |
登录后下载/点赞/收藏 ❤ 2 | ★ 0
add-observability-express

目录结构

SKILL.md

举报内容

提示
