Skip to content

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 ​

  1. ODP đã có tính năng này chưa? → xem §3. Nếu có, dùng lại, không tự viết.
  2. 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.
  3. Chỉ import từ @odp/api/types. Không import deep path (@odp/api/dist/..., src/...). → §4.
  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ới accountability của request. ItemsService chạ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ảng odp_*.
  5. context.database (Knex thô) chỉ dùng khi thật sự cần — ItemsService khô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.
  6. Khai báo quyền ở package.json#odp-extension.permissions; kiểm tra trong endpoint bằng context.validateAppAccess(...).
  7. 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ạiDùng khi
hookPhản ứng theo sự kiện vòng đời (before/after CRUD, submit version, server start...)
endpointThêm HTTP route mới
bundleGộ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áo odp-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ùngKhô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ấtQuery/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 ghiHook 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 routeendpoint: 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 notificationcontext.services.NotificationsServiceGhi thẳng odp_notifications
Kiểm tra quyền truy cập moduleawait context.validateAppAccess(accountability, module, action, scope, knex)Tự kiểm tra role/permission
Lấy schema collection/fieldawait 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/stopHook context.init('server.start', fn)
Lưu dữ liệu riêng của extensionTạ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 khamcontext.database (Knex) — chỉ khi thật cần, tự lo permissionDùng raw DB cho CRUD thông thường
Quản lý collection/field độngcontext.services.CollectionsService / FieldsService / RelationsServiceDDL Knex thủ công trên schema hệ thống
Versioning / duyệt nội dungcontext.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á → throw cá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...).
  • ApiExtensionContext và các method công khai của context.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ảng odp_*.
  • 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/types hoặc ApiExtensionContext hoặc danh sách sự kiện trên → coi như nội bộ, đừng đụng.


5. DO / DON'T ​

✅ DO ​

  • Dùng context.services cho mọi nghiệp vụ; truyền accountability củ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ống context.database (raw) khi ItemsService thậ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ằng validateAppAccess.
  • Hook tự ghi lại → { emitEvents: false }.
  • Lỗi: throw error 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.database cho CRUD — đó là lựa chọn cuối, không phải mặc định; CRUD (kể cả collection riêng) đi qua ItemsService trướ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 — tryConsume trả 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/tryConsume lazy — trong request handler, scheduled job, action handler, hoặc init sau extensions.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:
    ts
    interface 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ầnDùngKhông làm
A cấp service cho Bctx.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 undefinedconsume top-level; giả định A luôn có
B bắt buộc cần Actx.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 contractstring 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 idContractDùng để
ai.engineAiEngine (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.engineWorkflowEngineApiresolveNode(instanceStepId, input) — advance một external workflow node.
workflow.nodes / workflow.actionsWorkflowNodeRegistry / WorkflowActionRegistryĐăng ký node/action type mới cho workflow engine.
mcp.toolsMcpToolRegistry (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ắcGiá trị (MCP_LIMITS)
Namespace^[a-z][a-z0-9_]{1,23}$ (thường là extension id)
Namespace cấmCó 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ự
descriptionBắt buộc, khác rỗng, tối đa 1024 ký tự — ngắn, keyword đứng đầu
instructions, guide contentTối đa 16 000 ký tự
groupKhớp ^[a-z][a-z0-9_]*$; mặc định = namespace (toolset id cho ?toolsets=)
Guide topicBằ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ởi mcp_allowed_collections.
  • access: 'write' — thêm mcp_read_only_collections; phải khai báo deletes: true | false. deletes: true → tool bị ẩn khi mcp_allow_deletes tắt.
  • collections — mảng tên collection hoặc hàm (args) => string[] | Promise<string[]>. Hàm không nhận knex.
  • inputSchema.type phải là 'object'; handler phả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ới accountability này, theo §0–§5. Không dùng accountability: 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 / deep và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".
  • destructive mặc định true cho tool write (annotation destructiveHint); openWorld mặc định false.

Vòng đời.

  • register throw 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.
  • register lại cùng namespace → thay thế toàn bộ tool + guide của namespace đó (hot reload).
  • register trả 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.registry gắ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ậtGiá 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ạnsâ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ácBuffer/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 details cấp đầu → giữ nguyên ở app, Collector hash sha256(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_email không phải key định danh: được log nguyên văn. Muốn hash → dùng đúng key email.

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ắng odp-extension.logLevel trong manifest; không bao giờ thấp hơn LOG_LEVEL.
  • Mỗi extension có một bucket chung cho mọi kind và child: EXTENSION_LOG_RATE dò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òng extension log rate cap hit kèm số dòng bị bỏ. Collector chỉ giữ 10% dòng trace/debug của extension.
  • Chi tiết env: Environment variables.

request.log, context.logger hay scopedApp.log ​

LoggerCó identity extensionSanitize sâu + rate capreqId + traceDùng khi
context.loggercó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.logcókhôngkhôngKhô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ới name = 'ext-security'. Nó không ghi vào bảng odp_security_events và không bao giờ mang name = 'security', nên không giả được event của core.
  • critical kích alert odp_api_ext_security_critical (Mattermost: [EXT <id>] ext.<id>.<type>).
  • Trả false khi event bị từ chối (sai type/severity/field) hoặc quá giới hạn; không bao giờ throw. Lý do từ chối có ở dòng debug extension 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_RATE event/giây (burst 100; event bị từ chối cũng tính); EXTENSION_AUDIT_CRITICAL_PER_MIN critical/phút (mặc định 10), quá thì gửi thành warning với details.downgraded: "critical_rate".
  • Không dùng context.logger cho audit: các key category, severity, event_type bị 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.

ODP Internal API Documentation