iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
🗂

I built a tool to convert HAR files into sequence diagrams

に公開

Overview

Visualizing the flow of HTTP requests and responses is extremely effective for understanding how web services operate. When requests pass through various endpoints, it becomes necessary to explain to new members which endpoints are accessed and in what order. While it would be easy if documents containing sequence diagrams were always kept up to date, manual management is quite challenging.

To make document creation easier, I created a tool that automatically generates Mermaid.js sequence diagrams from HAR files.

https://github.com/tasuku43/har2sequence

Here is an example of the execution:

$ har2sequence -config config.yaml -har ./www.google.com.har
sequenceDiagram
    participant Browser
    participant www.google.com
    participant ogs.google.com
    Browser->>www.google.com: 🟢 GET /
    activate www.google.com
    www.google.com-->>Browser: 200
    deactivate www.google.com
    Browser->>www.google.com: 🟢 GET /complete/search
    activate www.google.com
    www.google.com-->>Browser: 200
    deactivate www.google.com
    Browser->>www.google.com: 🟢 GET /client_204
    activate www.google.com
    www.google.com-->>Browser: 204
    deactivate www.google.com
    Browser->>www.google.com: 🟢 GET /async/hpba
    activate www.google.com
    www.google.com-->>Browser: 200
    deactivate www.google.com
    Browser->>ogs.google.com: 🟢 GET /u/0/widget/app
    activate ogs.google.com
    ogs.google.com-->>Browser: 200
    deactivate ogs.google.com

In this article, I will introduce how to use the created tool. (This is primarily a translation of the README content.)

(*By the way, since I made this almost entirely for personal use, error handling and such are very rough!)

What is har2sequence?

"har2sequence" is a tool that analyzes HAR files and generates sequence diagrams based on their content. By using this tool, you can represent the flow of HTTP requests and responses as visual diagrams that can be understood intuitively. Below, I will explain the main features and usage in detail.

Main Features

  • Read HAR files: Analyzes HAR files and extracts HTTP request and response data.
  • Generate sequence diagrams: Uses mermaid.js to generate sequence diagrams from HAR data. This visually displays the flow of HTTP requests and responses.
  • Configuration file support: Allows customization of participants, excluded paths, message prefixes, and more using a YAML configuration file.

Installation

"har2sequence" can be installed by downloading pre-built binary files. Use the following commands to download the appropriate binary and place it in a directory included in your environment's $PATH.

On Mac, you might need sudo for both curl and chmod. Personally, I'm not a fan of using administrative privileges unnecessarily, so I've created a separate directory for my own commands and added it to my $PATH.

curl -L -o /<your-PATH-directory>/har2sequence https://github.com/tasuku43/har2sequence/releases/download/v0.1.0/har2sequence-<your-os-and-arch>
chmod +x /<your-PATH-directory>/har2sequence

For example, for Mac (arm64), use the following commands:

curl -L -o /path/to/bin/har2sequence https://github.com/tasuku43/har2sequence/releases/download/v0.1.0/har2sequence-macos-arm64
chmod +x /path/to/bin/har2sequence

Usage

To use "har2sequence", run the following command:

har2sequence -config <path_to_config_file> -har <path_to_har_file>

For example, if you use a configuration file named config.yaml and a HAR file named example.har, run the following command:

har2sequence -config config.yaml -har example.har

Configuration File Example

Configuration files are written in YAML format. Below is an example of config.yaml.

participants:
  - "example.com"
  - "api.example.com"
excludePaths:
  - "example.com/exclude-this-path"
  - "api.example.com/exclude-this-path"
messagePrefixes:
  GET: "🟢 "
  POST: "🟠 "
  PUT: "🟣 "
  PATCH: "🟡 "
  DELETE: "🔴 "

Explanation of Config Parameters

  • participants: A list of domains to include in the sequence diagram. Only the domains specified here will be displayed in the diagram. If you don't narrow this down, many irrelevant requests and responses will be included. If unspecified, all domains will be displayed in the sequence diagram.
  • excludePaths: A list of URL paths to exclude from the sequence diagram. The paths specified here will not be displayed. This is useful when you want to exclude, for example, fetches for JS or CSS files. See the case study below for specific usage examples.
  • messagePrefixes: A map of prefixes for each HTTP method used in the sequence diagram. For example, you can set a prefix such as "🟢" for GET requests. Having colors makes it much easier to distinguish them visually!

Case Study: Generating a Sequence Diagram of Google's Homepage

Here is an example of generating a sequence diagram using a HAR file captured when accessing Google's homepage.
I use Chrome, so I obtained the HAR file using the following steps:
https://support.google.com/admanager/answer/10358597?hl=en

Configuration File Example

participants:
  - "www.google.com"
  - "ogs.google.com"
excludePaths:
  - "www.google.com/js"
  - "www.google.com/xjs"
  - "www.google.com/images"
  - "www.google.com/gen_204"
messagePrefixes:
  GET: "🟢 "
Generating the Sequence Diagram

Run the following command:

har2sequence -config config.yaml -har ./www.google.com.har
Example of the Generated Sequence Diagram

This sequence diagram illustrates the flow of HTTP requests and responses when accessing Google's homepage.

Dependencies

This project uses the following dependencies:

  • gopkg.in/yaml.v2: Used for parsing YAML configuration files.

Side Note

Both the implementation and the README description were mostly done by GPT-4o and GitHub Copilot. I started by telling it, "I want to create Mermaid.js sequence diagrams from HAR files using Go," and then gave instructions like, "I want you to create this struct," or "I want this logic to be handled by this struct," and it handled the implementation progressively, which was a huge help.

When I said, "Write a README!" it produced something about 70% complete, which I then fine-tuned.

AI is amazing!!

Discussion