RuntimeAnalyzeProfilerTrace

Instructions

Implementation Reference

• src/handlers/system/readonly/handleRuntimeAnalyzeProfilerTrace.ts:123-175 (handler)

  Main handler function that executes the tool logic: reads profiler trace (hitlist, statements, or db_accesses) via AdtRuntimeClient, parses the response, and returns a compact analysis summary with top entries.

  export async function handleRuntimeAnalyzeProfilerTrace(
    context: HandlerContext,
    args: RuntimeAnalyzeProfilerTraceArgs,
  ) {
    const { connection, logger } = context;
  
    try {
      if (!args?.trace_id_or_uri) {
        throw new Error('Parameter "trace_id_or_uri" is required');
      }
  
      const view = args.view ?? 'hitlist';
      const runtimeClient = new AdtRuntimeClient(connection, logger);
      const profiler = runtimeClient.getProfiler();
      const response =
        view === 'hitlist'
          ? await profiler.getHitList(args.trace_id_or_uri, {
              withSystemEvents: args.with_system_events,
            })
          : view === 'statements'
            ? await profiler.getStatements(args.trace_id_or_uri, {
                withSystemEvents: args.with_system_events,
              })
            : await profiler.getDbAccesses(args.trace_id_or_uri, {
                withSystemEvents: args.with_system_events,
              });
  
      const parsedPayload = parseRuntimePayloadToJson(response.data);
      const summary = pickTopEntries(parsedPayload, args.top ?? 10);
  
      return return_response({
        data: JSON.stringify(
          {
            success: true,
            trace_id_or_uri: args.trace_id_or_uri,
            view,
            status: response.status,
            summary,
            payload: parsedPayload,
          },
          null,
          2,
        ),
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
        config: response.config,
      });
    } catch (error: unknown) {
      logger?.error('Error analyzing profiler trace:', error);
      return return_error(error);
    }
  }

• src/handlers/system/readonly/handleRuntimeAnalyzeProfilerTrace.ts:6-34 (schema)

  TOOL_DEFINITION export containing the tool name 'RuntimeAnalyzeProfilerTrace', availability (onprem/cloud), description, and inputSchema with parameters trace_id_or_uri (required), view, top, with_system_events.

  export const TOOL_DEFINITION = {
    name: 'RuntimeAnalyzeProfilerTrace',
    available_in: ['onprem', 'cloud'] as const,
    description:
      '[runtime] Read profiler trace view and return compact analysis summary (totals + top entries).',
    inputSchema: {
      type: 'object',
      properties: {
        trace_id_or_uri: {
          type: 'string',
          description: 'Profiler trace ID or full trace URI.',
        },
        view: {
          type: 'string',
          enum: ['hitlist', 'statements', 'db_accesses'],
          default: 'hitlist',
        },
        top: {
          type: 'number',
          description: 'Number of top rows for summary. Default: 10.',
        },
        with_system_events: {
          type: 'boolean',
          description: 'Include system events.',
        },
      },
      required: ['trace_id_or_uri'],
    },
  } as const;

• src/handlers/system/readonly/handleRuntimeAnalyzeProfilerTrace.ts:36-41 (schema)

  TypeScript interface RuntimeAnalyzeProfilerTraceArgs defining the typed arguments for the handler.

  interface RuntimeAnalyzeProfilerTraceArgs {
    trace_id_or_uri: string;
    view?: 'hitlist' | 'statements' | 'db_accesses';
    top?: number;
    with_system_events?: boolean;
  }

• src/lib/handlers/groups/SystemHandlersGroup.ts:69-72 (registration)

  Import of handleRuntimeAnalyzeProfilerTrace function and its TOOL_DEFINITION aliased as RuntimeAnalyzeProfilerTrace_Tool from the handler file.

  import {
    handleRuntimeAnalyzeProfilerTrace,
    TOOL_DEFINITION as RuntimeAnalyzeProfilerTrace_Tool,
  } from '../../../handlers/system/readonly/handleRuntimeAnalyzeProfilerTrace';

• src/lib/handlers/groups/SystemHandlersGroup.ts:160-164 (registration)

  Registration of the tool in SystemHandlersGroup: maps the toolDefinition to the handler that calls handleRuntimeAnalyzeProfilerTrace(this.context, args).

  {
    toolDefinition: RuntimeAnalyzeProfilerTrace_Tool,
    handler: (args: any) =>
      handleRuntimeAnalyzeProfilerTrace(this.context, args),
  },