performance_start_trace

Instructions

Implementation Reference

• src/tools/performance.ts:43-101 (handler)

  The main handler function that checks if a trace is already running, starts Puppeteer tracing with specific categories on the selected page, optionally reloads the page before and after starting, and handles auto-stop by waiting 5 seconds and calling the stop helper.

  handler: async (request, response, context) => {
    if (context.isRunningPerformanceTrace()) {
      response.appendResponseLine(
        'Error: a performance trace is already running. Use performance_stop_trace to stop it. Only one trace can be running at any given time.',
      );
      return;
    }
    context.setIsRunningPerformanceTrace(true);
  
    const page = context.getSelectedPage();
    const pageUrlForTracing = page.url();
  
    if (request.params.reload) {
      // Before starting the recording, navigate to about:blank to clear out any state.
      await page.goto('about:blank', {
        waitUntil: ['networkidle0'],
      });
    }
  
    // Keep in sync with the categories arrays in:
    // https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/panels/timeline/TimelineController.ts
    // https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/gather/gatherers/trace.js
    const categories = [
      '-*',
      'blink.console',
      'blink.user_timing',
      'devtools.timeline',
      'disabled-by-default-devtools.screenshot',
      'disabled-by-default-devtools.timeline',
      'disabled-by-default-devtools.timeline.invalidationTracking',
      'disabled-by-default-devtools.timeline.frame',
      'disabled-by-default-devtools.timeline.stack',
      'disabled-by-default-v8.cpu_profiler',
      'disabled-by-default-v8.cpu_profiler.hires',
      'latencyInfo',
      'loading',
      'disabled-by-default-lighthouse',
      'v8.execute',
      'v8',
    ];
    await page.tracing.start({
      categories,
    });
  
    if (request.params.reload) {
      await page.goto(pageUrlForTracing, {
        waitUntil: ['load'],
      });
    }
  
    if (request.params.autoStop) {
      await new Promise(resolve => setTimeout(resolve, 5_000));
      await stopTracingAndAppendOutput(page, response, context);
    } else {
      response.appendResponseLine(
        `The performance trace is being recorded. Use performance_stop_trace to stop it.`,
      );
    }
  },

• src/tools/performance.ts:31-42 (schema)

  Zod input schema defining optional boolean parameters 'reload' and 'autoStop' for controlling page reload and automatic stopping of the trace.

  schema: {
    reload: z
      .boolean()
      .describe(
        'Determines if, once tracing has started, the page should be automatically reloaded.',
      ),
    autoStop: z
      .boolean()
      .describe(
        'Determines if the trace recording should be automatically stopped.',
      ),
  },

• src/tools/performance.ts:23-102 (registration)

  Tool definition and export using defineTool, including name 'performance_start_trace', description, category annotation, schema, and inline handler.

  export const startTrace = defineTool({
    name: 'performance_start_trace',
    description:
      'Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.',
    annotations: {
      category: ToolCategories.PERFORMANCE,
      readOnlyHint: true,
    },
    schema: {
      reload: z
        .boolean()
        .describe(
          'Determines if, once tracing has started, the page should be automatically reloaded.',
        ),
      autoStop: z
        .boolean()
        .describe(
          'Determines if the trace recording should be automatically stopped.',
        ),
    },
    handler: async (request, response, context) => {
      if (context.isRunningPerformanceTrace()) {
        response.appendResponseLine(
          'Error: a performance trace is already running. Use performance_stop_trace to stop it. Only one trace can be running at any given time.',
        );
        return;
      }
      context.setIsRunningPerformanceTrace(true);
  
      const page = context.getSelectedPage();
      const pageUrlForTracing = page.url();
  
      if (request.params.reload) {
        // Before starting the recording, navigate to about:blank to clear out any state.
        await page.goto('about:blank', {
          waitUntil: ['networkidle0'],
        });
      }
  
      // Keep in sync with the categories arrays in:
      // https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/panels/timeline/TimelineController.ts
      // https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/gather/gatherers/trace.js
      const categories = [
        '-*',
        'blink.console',
        'blink.user_timing',
        'devtools.timeline',
        'disabled-by-default-devtools.screenshot',
        'disabled-by-default-devtools.timeline',
        'disabled-by-default-devtools.timeline.invalidationTracking',
        'disabled-by-default-devtools.timeline.frame',
        'disabled-by-default-devtools.timeline.stack',
        'disabled-by-default-v8.cpu_profiler',
        'disabled-by-default-v8.cpu_profiler.hires',
        'latencyInfo',
        'loading',
        'disabled-by-default-lighthouse',
        'v8.execute',
        'v8',
      ];
      await page.tracing.start({
        categories,
      });
  
      if (request.params.reload) {
        await page.goto(pageUrlForTracing, {
          waitUntil: ['load'],
        });
      }
  
      if (request.params.autoStop) {
        await new Promise(resolve => setTimeout(resolve, 5_000));
        await stopTracingAndAppendOutput(page, response, context);
      } else {
        response.appendResponseLine(
          `The performance trace is being recorded. Use performance_stop_trace to stop it.`,
        );
      }
    },
  });

• src/tools/performance.ts:159-188 (helper)

  Helper function called when stopping the trace (auto or manual), parses the trace buffer using trace-processing functions, stores the result if successful, appends summary or error to response, and resets the running trace flag.

  async function stopTracingAndAppendOutput(
    page: Page,
    response: Response,
    context: Context,
  ): Promise<void> {
    try {
      const traceEventsBuffer = await page.tracing.stop();
      const result = await parseRawTraceBuffer(traceEventsBuffer);
      response.appendResponseLine('The performance trace has been stopped.');
      if (traceResultIsSuccess(result)) {
        context.storeTraceRecording(result);
        const traceSummaryText = getTraceSummary(result);
        response.appendResponseLine(traceSummaryText);
      } else {
        response.appendResponseLine(
          'There was an unexpected error parsing the trace:',
        );
        response.appendResponseLine(result.error);
      }
    } catch (e) {
      const errorText = e instanceof Error ? e.message : JSON.stringify(e);
      logger(`Error stopping performance trace: ${errorText}`);
      response.appendResponseLine(
        'An error occurred generating the response for this trace:',
      );
      response.appendResponseLine(errorText);
    } finally {
      context.setIsRunningPerformanceTrace(false);
    }
  }