Appearance
Extension Guardrails — ranh giới khi viết extension cho ODP
Đọc tài liệu này trước khi code một extension (đặc biệt nếu bạn là AI agent). Mục tiêu: làm đúng việc, đúng chỗ; không làm lại thứ ODP đã có; không chạm vào nội bộ core để sau này update core không làm vỡ extension.
Bản đồ kiến trúc + bề mặt extension theo từng phần: Backend API Sitemap. Cách scaffold/build/dev: Extension Development.
0. Checklist trước khi viết bất kỳ dòng code nào
- ODP đã có tính năng này chưa? → xem §3. Nếu có, dùng lại, không tự viết.
- Cần Hook hay Endpoint? → §2. Hook = phản ứng theo sự kiện/biến đổi dữ liệu; Endpoint = thêm HTTP route mới.
- Chỉ import từ
@odp/api/types. Không import deep path (@odp/api/dist/...,src/...). → §4. - Mọi CRUD (kể cả collection riêng của extension) → ưu tiên cao nhất
context.services.ItemsService(collection, { knex, accountability, schema })vớiaccountabilitycủa request.ItemsServicechạy được trên collection custom, và chỉ qua nó bạn mới có permission + audit/activity + revision + parsing query (filter/sort/aggregate/relation). Không query thẳng bảngodp_*. context.database(Knex thô) chỉ dùng khi thật sự cần —ItemsServicekhông biểu đạt được (query quá phức tạp, luồng lớn cần transaction bọc thủ công, bulk/aggregation đặc thù). Hiểu rõ: raw DB bỏ qua permission, audit log và parsing query.- Khai báo quyền ở
package.json#odp-extension.permissions; kiểm tra trong endpoint bằngcontext.validateAppAccess(...). - Không monkey-patch, không mở server/port riêng, không bypass permission. → §5.
Nếu một yêu cầu không thể thực hiện trong ranh giới này → dừng và hỏi, đừng "chế" giải pháp luồn lách.
1. Extension là gì — và bề mặt được phép dùng
Một extension là package có package.json với khối odp-extension. 3 loại:
| Loại | Dùng khi |
|---|---|
hook | Phản ứng theo sự kiện vòng đời (before/after CRUD, submit version, server start...) |
endpoint | Thêm HTTP route mới |
bundle | Gộp cả hook + endpoint trong 1 extension (khuyến nghị) |
Toàn bộ những gì extension được phép chạm gói trong ApiExtensionContext (truyền vào hook/endpoint):
ts
import { defineHook, defineEndpoint } from '@odp/api/types';
interface ApiExtensionContext {
services; // các service class: ItemsService, UsersService, ... (dùng cho mọi nghiệp vụ)
emitter; // onFilter/onAction/onInit (hook) + emitFilter/emitAction/emitInit (phát event)
database; // Knex thô — CHỈ khi ItemsService không đủ (xem §2); bỏ qua permission/audit/parsing
getSchema(); // SchemaOverview hiện tại
env; // cấu hình (không có credential của core)
logger; // ExtensionLogger: log có sanitize + giới hạn tốc độ — xem §7
audit; // ctx.audit.event(): audit event, namespace ext.<id>.<type> — xem §7
trace; // ctx.trace.headers(): traceparent cho service extension tự sở hữu — xem §7
validateAppAccess; // kiểm tra app-permission trong endpoint
registry; // chia sẻ service giữa các extension (provide/consume) — xem §6
exceptions; // class lỗi 4xx để throw (InvalidPayloadError, ForbiddenError, NotFoundError, ...) — xem §2
}Hook nhận (context); endpoint nhận (router /* Fastify scoped */, context). Đó là toàn bộ bề mặt được hỗ trợ — ngoài phạm vi này là nội bộ.
Extension id. Id cuối cùng (lấy từ odp-extension.id, nếu không có thì từ tên folder hoặc tên package) phải khớp ^[a-z0-9][a-z0-9-]{0,63}$. Id nằm trong mọi dòng log, mọi alert, namespace cache và module app-permission.
- Id sai → manifest bị từ chối (A-06), log
Invalid extension id — extension not loaded. Lỗi gợi ý một id hợp lệ (set odp-extension.id to "..."), nhưng core không tự áp id đó. Extension npm có scope (@acme/x) hoặc folder có tên ngoài định dạng phải khai báoodp-extension.id. - Id trùng trong cùng một nguồn (2 folder local, hoặc 2 package module) → extension thứ hai không được load, log
Duplicate extension id — the second extension is not loaded. - Id trùng giữa local và module → bản local được load, log warn
Extension id used by a local extension and a module extension — the local one is loaded.
2. Làm gì → ở đâu
| Bạn cần... | Dùng | Không làm |
|---|---|---|
| CRUD trên một collection (kể cả collection riêng của extension) | new context.services.ItemsService(coll, { knex, accountability, schema }) — ưu tiên cao nhất | Query/Knex thô (mất permission/audit/parsing) |
| Phản ứng khi item tạo/sửa/xoá | Hook context.action('items.create' | 'items.update' | 'items.delete', fn) hoặc scoped '<collection>.items.create' | Polling DB, trigger DB thủ công |
| Sửa/validate payload trước khi ghi | Hook context.filter('items.create', fn) (trả payload đã sửa, hoặc throw để chặn) | Sửa dữ liệu sau khi đã ghi |
| Chặn request với lỗi 4xx rõ ràng (thay vì 500 chung chung) | throw new meta.exceptions.InvalidPayloadError({ reason }) (hoặc ForbiddenError, NotFoundError, ConflictError, ...) | throw new Error(...) — rơi vào 500 "An unexpected error occurred" |
| Thêm HTTP route | endpoint: router.get('/path', handler) (prefix tự gắn theo id) | Mở Fastify/HTTP server riêng |
| Gửi thông báo (email/in-app/mattermost) | context.emitter.emitAction('notify.trigger', { template_id, recipients, variables }, ctx) | Tự gọi SMTP/HTTP gửi mail |
| Tạo in-app notification | context.services.NotificationsService | Ghi thẳng odp_notifications |
| Kiểm tra quyền truy cập module | await context.validateAppAccess(accountability, module, action, scope, knex) | Tự kiểm tra role/permission |
| Lấy schema collection/field | await context.getSchema() | Đọc thẳng odp_collections/_fields |
| Chạy định kỳ (cron) | Hook context.schedule('*/5 * * * *', fn) | setInterval toàn cục |
| Chạy khi server start/stop | Hook context.init('server.start', fn) | |
| Lưu dữ liệu riêng của extension | Tạo collection (CollectionsService) rồi CRUD qua ItemsService(collection, {...}) | Nhồi vào odp_*; mặc định nhảy sang context.database |
Query quá phức tạp / transaction lớn / bulk mà ItemsService không kham | context.database (Knex) — chỉ khi thật cần, tự lo permission | Dùng raw DB cho CRUD thông thường |
| Quản lý collection/field động | context.services.CollectionsService / FieldsService / RelationsService | DDL Knex thủ công trên schema hệ thống |
| Versioning / duyệt nội dung | context.services.VersionsService + workflow (event versions.submit) | Tự xây versioning |
Khi hook tự ghi lại đúng collection mình đang lắng nghe → truyền
{ emitEvents: false }để tránh vòng lặp vô hạn.
3. ODP đã có sẵn — DÙNG, không viết lại
Trước khi định "tự xử lý", kiểm tra danh sách này. Hầu hết nhu cầu đã có service tương ứng (đầy đủ trong Sitemap):
- CRUD + query (filter
_eq/_in/_and/_or, sort, aggregate, search, phân trang) →ItemsService/ query engine. Đừng tự parse query hay viết SQL. - Permission field-level & row-level → tự áp dụng khi gọi service kèm
accountability. Đừng tự lọc quyền. - Auth / session / SSO / sub-token / impersonation →
AuthService,SubTokenService,ImpersonationService. Đừng tự làm JWT/login. - Versioning, revisions, activity log, comments →
VersionsService,RevisionsService,ActivityService,CommentsService. - Files + transform ảnh + storage (local/s3) + upload resumable →
FilesService,AssetsService. Đừng tự xử lý upload/resize. - Thông báo đa kênh + template + queue → event
notify.trigger/NotificationsService. Đừng tự gửi mail. - Workflow duyệt nhiều bước → định nghĩa workflow + trigger qua
versions.submit/items.*. Đừng tự xây state machine duyệt. - Settings, presets, translations/i18n, shares →
SettingsService,PresetsService,TranslationsService,SharesService. - GraphQL, WebSocket realtime →
GraphQLService,WebSocketService. - Lỗi chuẩn hoá →
throwcác error từ hệ thống (đừng tự định nghĩa format lỗi HTTP).
4. Cam kết ổn định vs Nội bộ (để update core không vỡ extension)
Core chỉ cam kết giữ ổn định bề mặt công khai. Phụ thuộc vào nội bộ = bản update core sau này sẽ làm vỡ extension của bạn.
✅ Được phép phụ thuộc (ổn định)
- Import từ
@odp/api/types:defineHook,defineEndpoint, và các type (ApiExtensionContext,HookConfig,EndpointConfig...). ApiExtensionContextvà các method công khai củacontext.services.*.- Sự kiện có tài liệu:
items.create/update/delete/read(+<collection>.items.*),items.sort,versions.submit,collections.*,fields.*,sub-tokens.create/revoke,notify.trigger,extensions.register,server.start/stop. - Manifest
odp-extension(id, type, path/entries, permissions). - CLI:
odp,odp-extension.
❌ KHÔNG được phụ thuộc (nội bộ — có thể đổi bất cứ lúc nào)
- Import deep path:
@odp/api/dist/...,service/api/src/..., hay bất cứ gì ngoài@odp/api/types. - Internals: AST query engine,
security/*, middleware, DB dialects,permissions/*(hàm validate-*), cấu trúc bảngodp_*. - Method/field không có tài liệu của service.
- Hành vi phụ (side-effect) không được cam kết.
Quy tắc vàng: nếu nó không nằm trong
@odp/api/typeshoặcApiExtensionContexthoặc danh sách sự kiện trên → coi như nội bộ, đừng đụng.
5. DO / DON'T
✅ DO
- Dùng
context.servicescho mọi nghiệp vụ; truyềnaccountabilitycủa request để giữ đúng quyền. - Dữ liệu riêng của extension → tạo collection rồi CRUD qua
ItemsService(ưu tiên cao nhất — có permission/audit/parsing). Chỉ rơi xuốngcontext.database(raw) khiItemsServicethật sự không kham (query quá phức tạp, transaction lớn, bulk) — và hiểu là bỏ qua permission/audit/parsing. - Thêm route qua
endpoint; khai báo quyền ở manifest; kiểm bằngvalidateAppAccess. - Hook tự ghi lại →
{ emitEvents: false }. - Lỗi:
throwerror chuẩn của hệ thống với thông điệp rõ ràng.
❌ DON'T (gồm các "chiêu trò" cấm)
- Làm lại tính năng đã có (CRUD, auth, permission, versioning, notify, files...) — xem §3.
- Import nội bộ/deep path. Chỉ
@odp/api/types. - Query/sửa thẳng bảng
odp_*— luôn qua service. - Mặc định nhảy sang
context.databasecho CRUD — đó là lựa chọn cuối, không phải mặc định; CRUD (kể cả collection riêng) đi quaItemsServicetrước. - Bypass permission: tránh
accountability: nullđể "cho nhanh"; chỉ dùng null cho thao tác system có chủ đích và hiểu rõ hậu quả. - Monkey-patch / override service, Fastify instance, prototype, global; ghi đè logic core.
- Hardcode SQL trùng logic core, hardcode URL/secret/credential.
- Mở HTTP server/port riêng, hay đăng ký route ngoài cơ chế
endpoint. - Phụ thuộc thứ tự side-effect hoặc chi tiết triển khai không cam kết.
- "Vá" tạm bằng cách đọc/sửa state nội bộ của core để đạt mục tiêu trước mắt.
6. Chia sẻ service giữa các extension (Service Registry)
Khi extension A muốn cấp một service cho extension B / endpoint / hook khác dùng (vd metaService dựng lúc boot với database/getSchema), không nhét vào context.services (đó là barrel core, không phải chỗ của extension) và không import trực tiếp module của A vào B (coupling cứng — A vắng mặt là B vỡ). Dùng context.registry.
ts
import { createServiceRef } from '@odp/api/types';
// Contract — CHỈ interface + ref, không implementation. A và B cùng import.
// Package này tự do: private nội bộ org, hay public khi open source — tuỳ bạn.
export interface MetaService { resolve(id: string): Promise<Meta> }
export const metaServiceRef = createServiceRef<MetaService>('myorg.meta');Provider (A) — đăng ký ở init 'extensions.register':
ts
export default defineHook((hook, ctx) => {
hook.init('extensions.register', () => {
ctx.registry.provide(metaServiceRef, new MetaServiceImpl(ctx.database, ctx.getSchema));
});
});Consumer (B) — đọc lazy (trong request handler / sau khi load xong); A có thể vắng:
ts
export default defineEndpoint((router, ctx) => {
router.get('/x', async () => {
const meta = ctx.registry.tryConsume(metaServiceRef); // typed | undefined
return meta ? meta.resolve('1') : fallback(); // A chưa cài → vẫn chạy
});
});Luật bắt buộc
- Phụ thuộc CONTRACT, không phụ thuộc PROVIDER. B import
metaServiceRef(contract), không bao giờ import A. A là một implementation, có thể vắng —tryConsumetrảundefined, đó là trạng thái hợp lệ, B phải degrade. provideởinit('extensions.register')(phase đăng ký, await tuần tự trước khi seal).consume/tryConsumelazy — trong request handler, scheduled job, action handler, hoặc init sauextensions.register. Không consume ở top-level body của hook (chạy trước seal → bị chặn).- Không cần contract chung được (vd ext 3rd-party, contract private không chia sẻ): dùng string id + interface tự khai +
has()— mất type-safety đổi lấy zero-coupling:tsinterface MetaLike { resolve(id: string): Promise<{ title: string }> } if (ctx.registry.has('myorg.meta')) { const meta = ctx.registry.tryConsume<MetaLike>('myorg.meta')!; }
Self-diagnosing (dev)
Consume trước khi load xong (sai kỷ luật) → tryConsume trả undefined + log error kèm stack (1 lần/id); consume (hard) → throw với message phân biệt "consumed before registry sealed" vs "no provider". Lỗi này deterministic theo tập extension → dev gặp ngay lần boot đầu, fix là hết.
| Cần | Dùng | Không làm |
|---|---|---|
| A cấp service cho B | ctx.registry.provide(ref, impl) ở init('extensions.register') | Nhét vào context.services; import module của A vào B |
| B dùng service của A (A optional) | ctx.registry.tryConsume(ref) lazy, degrade nếu undefined | consume top-level; giả định A luôn có |
| B bắt buộc cần A | ctx.registry.consume(ref) (throw nếu thiếu) | nuốt lỗi rồi chạy tiếp với state sai |
| Không share được contract | string id + has() + interface tự khai | ép import contract private của bên khác |
Ref core cấp sẵn (consume được ngay, không cần extension khác)
Core tự provide một số service lúc boot (trước khi seal), extension chỉ việc consume/tryConsume:
| Ref id | Contract | Dùng để |
|---|---|---|
ai.engine | AiEngine (modules/ai/engine-ref.ts) | Trigger một AI app bằng ID in-process — run(appId, input, options). Xem AI Engine → Programmatic trigger. |
workflow.engine | WorkflowEngineApi | resolveNode(instanceStepId, input) — advance một external workflow node. |
workflow.nodes / workflow.actions | WorkflowNodeRegistry / WorkflowActionRegistry | Đăng ký node/action type mới cho workflow engine. |
mcp.tools | McpToolRegistry (mcpToolsRef) | Đăng ký MCP tool + guide topic cho built-in MCP server — register({ namespace, tools, guides? }), has(name). Core provide trước extensions.register; consume trong init('app.before') bằng tryConsume(mcpToolsRef). Xem MCP tools từ extension. |
MCP tools từ extension
Contract của mcp.tools. Nguồn chân lý: src/types/extensions.ts (mục MCP tool registry) và src/modules/mcp/registry.ts. Cách server phục vụ tool: MCP Server.
Quy trình từng bước (layout, adapter, test, kiểm tích hợp): skill .claude/skills/odp-backend-ext-mcp/.
Import contract. mcpToolsRef, MCP_RESERVED_NAMESPACES, MCP_LIMITS và các type McpToolDefinition, McpToolScope, McpToolContext, McpGuideTopic, McpToolRegistration, McpToolRegistry từ @odp/extensions-sdk (bản mirror) hoặc @odp/api/types. Không import modules/mcp/*.
Thời điểm. Core gọi provideMcpRegistry trước extensions.register (src/index.ts). Extension consume trong init('app.before'): event này phát trong createServer() (src/server.ts), sau khi registry đã seal — đúng luật consume lazy ở trên.
ts
init('app.before', () => {
registry.tryConsume(mcpToolsRef)?.register({ namespace: 'projects', tools: [/* ... */], guides: [/* ... */] });
});Core cũ chưa có mcp.tools → tryConsume trả undefined → ?.register là no-op. Extension vẫn chạy, chỉ không có MCP tool.
Đặt tên.
| Quy tắc | Giá trị (MCP_LIMITS) |
|---|---|
| Namespace | ^[a-z][a-z0-9_]{1,23}$ (thường là extension id) |
| Namespace cấm | Có trong MCP_RESERVED_NAMESPACES hoặc bắt đầu bằng <reserved>_ |
| Tên tool | <namespace>_<verb>, khớp ^[a-z][a-z0-9_]*$, tối đa 48 ký tự |
description | Bắt buộc, khác rỗng, tối đa 1024 ký tự — ngắn, keyword đứng đầu |
instructions, guide content | Tối đa 16 000 ký tự |
group | Khớp ^[a-z][a-z0-9_]*$; mặc định = namespace (toolset id cho ?toolsets=) |
Guide topic | Bằng namespace hoặc bắt đầu bằng <namespace>_; title bắt buộc |
MCP_RESERVED_NAMESPACES: items, schema, collections, fields, relations, files, users, roles, policies, permissions, settings, versions, activity, workflow, odp, mcp, ai, notify, metrics, guide.
Group của core (toolset id): items, schema, files, users, access, settings, versions, activity, workflow, ai, notify, guide. Code chỉ cấm namespace, không cấm group — nhưng extension không được đặt group trùng một group core (quy ước): ?toolsets= sẽ trộn tool extension vào group core.
Scope bắt buộc (McpToolScope):
access: 'read'— bị ràng buộc bởimcp_allowed_collections.access: 'write'— thêmmcp_read_only_collections; phải khai báodeletes: true | false.deletes: true→ tool bị ẩn khimcp_allow_deletestắt.collections— mảng tên collection hoặc hàm(args) => string[] | Promise<string[]>. Hàm không nhận knex.inputSchema.typephải là'object';handlerphải là function.
Handler chỉ nhận { accountability, schema, logger } (McpToolContext) — không có knex, không có MCP settings. logger là ExtensionLogger của extension đã đăng ký tool: mỗi dòng mang extension.id của extension đó (không phải namespace), extension.kind = 'mcp_tool' và mcp.tool = <tên tool> (§7). Hệ quả:
- Handler phải tự áp đúng quyền như REST route tương ứng: CRUD qua
ItemsService(hoặc service khác) vớiaccountabilitynày, theo §0–§5. Không dùngaccountability: null. - P9 (allowlist / read-only) chỉ áp lên các collection khai báo trong
scope.collections. Dispatcher kiểm tra trước khi gọi handler. Collection handler chạm tới mà không khai báo → P9 không thấy. Kiểm tra quan hệ (fields/filter/deepvào collection khác) chỉ có ở core tool. adminOnly: true→ tool chỉ tồn tại với admin; với người khác là "unknown tool".destructivemặc địnhtruecho toolwrite(annotationdestructiveHint);openWorldmặc địnhfalse.
Vòng đời.
registerthrow khi vi phạm bất kỳ luật nào ở trên, khi một tool/topic trùng trong cùng lần đăng ký, hoặc trùng với namespace khác. Không có gì được ghi khi throw.registerlại cùng namespace → thay thế toàn bộ tool + guide của namespace đó (hot reload).registertrả về một handle; gọi handle → gỡ đăng ký (chỉ khi namespace chưa bị đăng ký lại).has(name)tra trên toàn catalog, kể cả core tool.- Tool đăng ký qua
context.registrygắn với extension: extension lỗi hoặc bị unload thì tool của nó bị gỡ (A-07).
7. Log, audit và trace
Nguồn chân lý: src/types/extensions.ts (ExtensionLogger, ExtensionAudit, ExtensionTrace), src/extensions/extension-logger.ts, src/modules/telemetry/*. Cách log đi tới OpenObserve: Telemetry.
context.logger (ExtensionLogger)
ExtensionLogger là một wrapper, không phải pino. Gọi theo các dạng của pino:
ts
context.logger.info('order %s placed', orderId);
context.logger.info({ order_id: orderId }, 'order placed');
context.logger.error(error, 'sync failed'); // → err: { type, message, stack }
const log = context.logger.child({ job: 'sync' }); // bindings đi qua cùng luật
if (log.isLevelEnabled('debug')) log.debug({ rows }, 'batch');| Có | Không có (breaking so với pino.Logger) |
|---|---|
trace debug info warn error fatal, child(bindings, options?) (bỏ qua options), isLevelEnabled(level), level (chỉ đọc), printf %s %d %i %f %o %O %j %% | level = ..., setLevel, levels, bindings(), flush(), silent(), on(), msgPrefix; truyền context.logger vào tham số kiểu pino.Logger |
Mỗi dòng core tự gắn: name = ext:<id>, extension.id, extension.version, extension.kind (hook | endpoint | schedule | mcp_tool), extension.entry (bundle), reqId, trace_id, span_id, trace_flags. Trong một lần chạy schedule, dòng của hook mang extension.kind = 'schedule' và reqId = run:<uuid>.
Key dành riêng. Core bỏ các key này khỏi data và khỏi bindings của child(), rồi ghi tên của chúng vào odp.dropped_keys. Key bị so ở dạng tên cột của OpenObserve: chữ thường, mọi ký tự ngoài [a-z0-9_] thành _, object lồng được làm phẳng bằng _. Vì vậy Name, SEVERITY, event.type, extension_id, { Extension: { Id } }, { event: { type } } đều bị bỏ.
- Cột dành riêng:
name,category,event_type,severity,level,msg,body,time,_timestamp,pid,hostname,reqid,correlation_id,trace_id,span_id,trace_flags,parent_span_id,run,extension,mcp_tool,mcpnamespace,res,req. - Tiền tố dành riêng:
extension_,odp_. - Lý do: các cột này quyết định routing của Collector và alert bảo mật. Nếu không chặn, một extension ghi
{ category: 'security', severity: 'critical' }sẽ kích alert của core.
Sanitize (tự động, ở mọi độ sâu, không sửa object gốc):
| Luật | Giá trị |
|---|---|
Key credential → [REDACTED] | key khớp pass(word), secret, token, otp, code_verifier, authorization, cookie, api_key, private_key, credential, session (không phân biệt hoa thường) |
Error ở mọi độ sâu | { type, message, stack } (message 1024, stack 4096 ký tự), cause theo 1 cấp |
| Giới hạn | sâu 6 cấp ([depth]), mảng 20 phần tử, chuỗi 256 ký tự, message 1024 ký tự, cả data 8 KiB JSON (quá → { odp.truncated: true, keys }) |
| Khác | Buffer/stream → [binary], Date → ISO, bigint → chuỗi, vòng tham chiếu → [circular] |
PII. 5 key định danh chuẩn: user_id, email, ip, phone, target_user (khớp chính xác tên key).
- Đặt ở cấp đầu của data hoặc trong
detailscấp đầu → giữ nguyên ở app, Collector hashsha256(PII_HASH_SALT + value)trước khi lưu. - Nằm sâu hơn → app che thành
[REDACTED](Collector không hash được ở đó). - Trong tham số printf (
%o,%j...) → luôn bị che. Chuỗi trong message không được hash: không đặt email/số điện thoại vào text của message. customer_emailkhông phải key định danh: được log nguyên văn. Muốn hash → dùng đúng keyemail.
Level và giới hạn tốc độ (operator quyết định, extension không đổi được):
- Level:
EXTENSION_LOG_LEVELS(id=level,*=level) thắngodp-extension.logLeveltrong manifest; không bao giờ thấp hơnLOG_LEVEL. - Mỗi extension có một bucket chung cho mọi kind và child:
EXTENSION_LOG_RATEdòng/giây (mặc định 50),EXTENSION_LOG_BURST(mặc định 500). Quá → dòng bị bỏ (cả stdout), mỗi 10 giây có đúng 1 dòngextension log rate cap hitkèm số dòng bị bỏ. Collector chỉ giữ 10% dòngtrace/debugcủa extension. - Chi tiết env: Environment variables.
request.log, context.logger hay scopedApp.log
| Logger | Có identity extension | Sanitize sâu + rate cap | reqId + trace | Dùng khi |
|---|---|---|---|---|
context.logger | có | có | có (trong request/run) | Mặc định cho mọi dòng của extension |
request.log (route của extension) | có | không (chỉ redact credential cấp đầu + 1 cấp) | có | Dòng gắn với một request, khi cần đúng logger của Fastify |
scopedApp.log / router.log | có | không | không | Không dùng trong handler: dòng ghi trong request không có reqId và trace |
context.audit.event()
ts
const accepted = context.audit.event({
type: 'export_done', // ^[a-z][a-z0-9_]{1,47}$ → event_type = ext.<id>.export_done
severity: 'critical', // info | warning | critical
user_id: accountability.user, // tùy chọn: user_id, target_user ^[A-Za-z0-9._:@+-]{1,128}$, collection ^[A-Za-z0-9_-]{1,64}$
details: { rows: 3 }, // tùy chọn, sanitize như log, tối đa 4 KiB
});- Event đi vào stream
odp_api_audit(90 ngày) vớiname = 'ext-security'. Nó không ghi vào bảngodp_security_eventsvà không bao giờ mangname = 'security', nên không giả được event của core. criticalkích alertodp_api_ext_security_critical(Mattermost:[EXT <id>] ext.<id>.<type>).- Trả
falsekhi event bị từ chối (saitype/severity/field) hoặc quá giới hạn; không bao giờ throw. Lý do từ chối có ở dòngdebugextension audit event refused. - Event được đọc một lần vào bản sao: getter đổi giá trị sau bước kiểm tra không có tác dụng.
- Giới hạn mỗi extension:
EXTENSION_AUDIT_RATEevent/giây (burst 100; event bị từ chối cũng tính);EXTENSION_AUDIT_CRITICAL_PER_MINcritical/phút (mặc định 10), quá thì gửi thànhwarningvớidetails.downgraded: "critical_rate". - Không dùng
context.loggercho audit: các keycategory,severity,event_typebị bỏ.
context.trace.headers()
Trả { traceparent, tracestate? } (W3C) với trace_id của request hoặc run hiện tại và một span id mới; ngoài request/run trả {}.
ts
await fetch(myServiceUrl, { headers: { ...context.trace.headers(), 'content-type': 'application/json' } });Chỉ gửi tới service mà extension tự sở hữu. Core không tự gửi traceparent ra bên thứ ba (OAuth/OpenID provider, Infobip, Mattermost, nhà cung cấp LLM, MCP server bên ngoài): trace_id phải ở trong ranh giới tin cậy.
Ví dụ đầy đủ
Extension mẫu service/api/test/modules/telemetry/fixtures/sample-telemetry/ (bundle: hook + endpoint + schedule + MCP tool) dùng context.logger, context.audit và context.trace. Đây là fixture cho live smoke, không cài ở production.
8. Khi bí
Nếu nhu cầu không làm được trong ranh giới trên (vd cần một sự kiện core chưa phát, cần một khả năng core chưa expose): dừng lại, ghi rõ cái còn thiếu, và đề xuất bổ sung vào core (thêm sự kiện/method công khai) — thay vì luồn lách nội bộ. Mở rộng bề mặt công khai của core là việc của core, không phải của extension.