Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,33 @@ OPENAI_API_KEY=
# Set this when using LiteLLM or another OpenAI-compatible gateway.
OPENAI_BASE_URL=

# Temporary read-only healthcheck source for validating LangChain tool calling.
# Server-owned Backend health endpoints used by backend_get_health.
AMDC_DEV_HEALTHCHECK_URL=https://example.com
AMDC_PROD_HEALTHCHECK_URL=https://example.com

# Server-owned Prometheus base URLs used by fixed read-only Prometheus tools.
AMDC_DEV_PROMETHEUS_URL=http://127.0.0.1:9090
AMDC_PROD_PROMETHEUS_URL=https://prometheus.example.com
# Direct user-MySQL diagnosis: dedicated read-only diagnostic account.
# Local host uses published port 33061; container-network mysql uses port 3306.
AMDC_DEV_MYSQL_HOST=
AMDC_DEV_MYSQL_PORT=33061
AMDC_DEV_MYSQL_USER=
AMDC_DEV_MYSQL_PASSWORD=
# Production requires a CA PEM string in TLS_CA.
AMDC_PROD_MYSQL_HOST=
AMDC_PROD_MYSQL_PORT=3306
AMDC_PROD_MYSQL_USER=
AMDC_PROD_MYSQL_PASSWORD=
AMDC_PROD_MYSQL_TLS_CA=

# ProxySQL Admin stats-only account, not the application/client port.
AMDC_DEV_PROXYSQL_HOST=
AMDC_DEV_PROXYSQL_PORT=6032
AMDC_DEV_PROXYSQL_USER=
AMDC_DEV_PROXYSQL_PASSWORD=
AMDC_PROD_PROXYSQL_HOST=
AMDC_PROD_PROXYSQL_PORT=6032
AMDC_PROD_PROXYSQL_USER=
AMDC_PROD_PROXYSQL_PASSWORD=
AMDC_PROD_PROXYSQL_TLS_CA=
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Gate Status: <blocked | ready_for_design | ready_for_implementation | ready_for_

- 의존성 또는 TypeScript 변경 후 `npm run typecheck`와 `npm run build`를 실행합니다.
- 의존성이 없거나 잠금 파일이 변경된 경우에만 `npm ci`를 사용합니다.
- 저장소에는 현재 자동화된 `test` 스크립트가 없습니다. 테스트가 통과했다고 보고하지 말고 이 공백과 가장 좁은 재현 가능한 간이 점검을 제시합니다.
- `npm test`는 현재 코드의 TypeScript 테스트 타입 검사와 테스트 실행을 포함합니다. 통과를 전체 P0 또는 실제 원천 검증 완료로 해석하지 않습니다.
- 단위, 통합, 동시성 검증은 사용자가 실제 환경을 명시적으로 승인하지 않는 한 가짜 제공자와 가짜 도구를 사용해야 합니다.

## AMDC 기본값
Expand Down
1 change: 1 addition & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ RUN npm run build
FROM node:22-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
RUN apk add --no-cache curl
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
Expand Down
89 changes: 89 additions & 0 deletions docs/mysql-tools.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Direct MySQL diagnostic tools

The mysql plugin includes only direct, parameterized read-only MySQL operations.
YAML owns each tool's input schema, fixed SELECT, filter predicates,
binding order, defaults, dependencies, ordering and environment-variable prefixes.
The `mysql_sql` executor in `src/tools/source-adapters/mysql-adapter.ts` contains
no tool-name dispatch or tool-specific SQL. It binds values through mysql2 prepared
statements; values never become SQL identifiers or clauses. Boolean options such
as includeIdle select a YAML-declared predicate via its `when` value.
Catalog definitions are trusted executable configuration: review their SQL and
use a least-privilege diagnostic account. SELECT syntax checks are not a SQL sandbox.

| Tool | Filters | Scope |
|---|---|---|
| mysql_list_databases | limit | All non-system databases visible to the diagnostic account |
| mysql_get_all_processlist | limit | All foreground connections except this query, including sleeping connections |
| mysql_get_active_processlist | limit | Non-sleeping foreground connections except this query |
| mysql_get_processlist_by_database | databaseName (required), includeIdle, limit | Foreground connections whose default database exactly matches the supplied database name |
| mysql_get_processlist_by_connection_id | connectionId (required) | One foreground connection identified by an observed MySQL backend connection ID |
| mysql_get_all_transactions | limit | All active InnoDB transactions, oldest first |
| mysql_get_transactions_by_connection_id | connectionId (required), limit | Active transactions owned by one observed MySQL backend connection |
| mysql_get_transaction_by_transaction_id | transactionId (required) | One active transaction identified by an observed InnoDB transaction ID |
| mysql_get_all_lock_waits | None | All InnoDB data-lock wait edges, capped at 100 with truncation flag |
| mysql_get_lock_waits_by_database | databaseName (required), limit | Lock-wait edges for objects in one database |
| mysql_get_lock_waits_by_table | databaseName and tableName (required), limit | Lock-wait edges for one exact table |
| mysql_get_lock_waits_by_connection_id | connectionId (required), limit | Lock-wait edges where one connection is waiter or blocker |

`mysqlUser` remains in returned rows but is not accepted as an input filter.
IDs are decimal strings, including returned connection and transaction IDs.
Input ID schemas enforce 1–20 decimal digits; limits use JSON Schema integer.
Each query fetches limit+1 rows; default limit 100, maximum 200. Results include
rows, returnedRows, truncated, collectedAt, appliedFilters and the effective limit.
appliedFilters records supplied filters plus any tool-defined filter defaults;
fixed scope restrictions from the table above still apply.
SQL text is capped at 4096
characters with statementTruncated. SQL text can contain application data;
existing-style secret scanning rejects known configured secrets and key/bearer
patterns, but is not general PII redaction. Do not persist raw results in traces.
LOCK_DATA is deliberately not selected.

For example, `mysql_get_all_processlist({})` reads all foreground connections;
`mysql_get_processlist_by_database({"databaseName":"sg"})` filters the connection default database.
Empty rows mean no matches within the applied scope at collection time, not proof
that the server is healthy.

Each call opens a dedicated connection and destroys it on completion, cancellation
or timeout. A connection arriving after timeout is immediately destroyed. The
server receives MAX_EXECUTION_TIME as well as the client deadline. Reads have a
5-second deadline and 64 KiB serialized result cap. The cap is checked after
fetching the bounded row count; it is not a streaming byte cap. Separate queries
are not one consistent snapshot; threads/transactions may disappear between reads.

## Connection setup

Use AMDC_DEV_MYSQL_HOST/PORT/USER/PASSWORD, or their PROD counterparts.
Production requires AMDC_PROD_MYSQL_TLS_CA containing the trusted CA PEM and
enables certificate verification. Connect directly to user MySQL, not the
ProxySQL client/admin port or metadata MySQL. Local Compose publishes user MySQL
at 33061; the mysql service's internal port is 3306. Hostnames depend on where AMDC
runs. No application/root/exporter credentials are automatically reused.

Provision a dedicated account with the required SELECT access to Performance
Schema and PROCESS visibility for INNODB_TRX, and verify its schema visibility.
SCHEMATA only lists schemas visible to the account: an empty result is not proof
that no database exists. Account creation/grants are a separate deployment step.
Unsupported tables/columns return source_unavailable; permission failures return
source_permission_denied. Neither becomes an empty successful result.

## Verification and remaining live checks

For an explicit local Docker integration check, rebuild the AMDC image and run
`AMDC_LOCAL_MYSQL_TEST=1 node scripts/mysql-live-check.mjs` with Docker on PATH.
This uses the existing local `mysql_1` root environment only for an isolated
fixture and the AMDC diagnostic account for tool reads. It creates a temporary
schema/account, checks filters, lock relationships, idle visibility, truncation,
invalid inputs and recovery, then removes its fixture. It never calls an LLM.

Automated tests exercise fixed query bindings, exact database/table/ID scopes,
invalid inputs, limits, raw output, secret/size rejection, permission
errors, deadline cleanup including late connections, and 12 concurrent fake calls.
They do not establish live SQL compatibility or live server overhead.

Before deployment, execute all eleven through the actual runtime using a diagnostic
account, then use an isolated test table and two test sessions to verify transaction
and lock IDs link correctly. Do not inject locks into existing application tables.
Verify privileges, actual MySQL 8.0 patch version, elapsed query time and server
impact. Prometheus metrics and AMDB metadata are outside the mysql plugin and must
be provided by their own plugins. No account provisioning or Git push is part of
this implementation.
15 changes: 12 additions & 3 deletions docs/prd/current/06-diagnostic-agent-tool-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,8 @@ R1이 숨겨서는 안 되는 호환성 사실:
- 현재 봇은 임시 표시 내용을 직접 보내며 리포트 영속화 경계가 없다.
- 현재 봇 기본 로그에는 설정된 길드 ID가 포함되어 목표 로깅 경계를 위반한다.
향후 담당자가 검토한 어댑터 변경 전까지 이를 유지한다.
- 현재 패키지에는 자동화된 `test` 스크립트가 없다.
- 위 기준 커밋(`develop@71f2069`)에는 자동화된 `test` 스크립트가 없었다.
이후 추가된 `npm test`는 테스트 실행 경로이며 정본 리포트 인계의 검증 완료를 뜻하지 않는다.

이는 향후 어댑터/호출 지점 공백이며 R0에서 제품 코드를 수정할 권한이 아니다.
이슈 #4는 가장 작은 상위 선행조건을 소유한다. 즉 각 관찰 결과/오류에 서버가 발급한
Expand Down Expand Up @@ -389,7 +390,7 @@ R0 문서 인수 조건:
2. 향후 `report-flow.ts` 추가와 위 `bot.ts` 호출 사슬 교체는 재경의 통합
검토가 필요하다. 진단 파이프라인/내부 소유권은 그대로 유지한다.
3. 정적 레지스트리와 YAML/전체 도구 노출의 비교는 별도 공동 결정이다.
4. 패키지에 `npm test`가 없어 구현 성공을 주장하지 않는다.
4. `npm test`가 추가됐어도 정본 리포트 인계의 구현 성공은 별도 검증해야 한다.
5. 이슈 #4는 최종 리포트 에이전트를 명시적으로 제외한다. 리포트/Discord 구현은
이슈 #7로 분리했고 `OstenHun`에게 할당했다. 이슈 #7의 GitHub 네이티브 `blocked-by #4`는
안정적인 도구 호출 근거와 성공/오류 순서를 보존하는 크기가 제한된 진단 출력
Expand Down Expand Up @@ -418,6 +419,12 @@ PRD 00/02와 충돌할 때 규범 계약으로 사용하지 않는다. 삭제
포함/제외와 성공 기준 표현은 모두 과거 제안의 인용이며
현재 구현 권한이나 인수 조건을 만들지 않는다. 이 기록은 과거 제안의 한국어 번역·재현이며 비규범적이다(원문 기준: develop@71f2069, PR #5/#6).

PR #11의 시제품은 Prometheus/ProxySQL/MySQL 조회 도구와 `rawResult` 반환을 확장했다.
일부 원시 조회 결과가 진단 에이전트의 Tool message에 전달되는 구현 상태는
`docs/prometheus-proxysql-tools.md`와 `docs/mysql-tools.md`에 기록한다.
이는 정본 Evidence 또는 리포트 입력 계약으로 승격되지 않으며, 원시 결과의
비밀정보 정제와 도구 호출 예산은 PRD 00/02에 맞춰 별도로 검증해야 한다.

### 제품 범위 (과도기 기록)

Diagnostic Agent의 제품 목표는 운영자가 입력한 장애 증상 또는 향후 Trigger가 만든
Expand Down Expand Up @@ -660,6 +667,7 @@ interface ToolRuntimeContext {
~~~ts
type ToolRuntimeResult =
| { ok: true; observation: ToolObservation }
| { ok: true; rawResult: RawToolResult }
| { ok: false; error: SanitizedToolError };
~~~

Expand All @@ -682,7 +690,8 @@ interface ToolObservation {
~~~

원시 원천 응답은 리포트 에이전트에 전달하지 않으며 증거로 저장하지 않는다.
정제되고 정규화된 관찰 결과만 도구 런타임 경계를 통과한다.
정본 경계에서는 정제되고 정규화된 관찰 결과만 전달한다. 위 `rawResult` 분기는
PR #11 시제품의 진단 Tool message 경로를 설명하며 정본 인계 허용을 뜻하지 않는다.

### 진단 에이전트 출력

Expand Down
Loading
Loading