Skip to content

[Bug] Fix: Examples are broken and unusable out-of-the-box, preventing user adoption #10

@Youming-FlowSpec

Description

@Youming-FlowSpec

Body:

Description

For a new user, the single most important experience is running the examples successfully. Currently, the
examples provided in the /examples directory are broken and fail to run, which creates a significant barrier to
understanding and adopting flowspec-cli.

This issue covers two main problems:

  1. The verify command fails because the provided JSON trace files are not in a supported format.
  2. The explore command example cannot be run because the required access.log file is missing.

Steps to Reproduce

Problem 1: verify command fails with invalid trace format

  1. Clone the repository.
  2. Build the project: make build
  3. Run the verify command with the provided YAML example:

1 ./build/flowspec-cli verify --path=examples/yaml-contracts/user-service.yaml
--trace=examples/yaml-contracts/test-traces/user-service-trace.json

Expected Behavior:
The command should execute successfully and produce a validation report, demonstrating how the verify command
works.

Actual Behavior:
The command fails with a fatal error:

1 level=error msg="Trace data ingestion failed: failed to detect trace format: unsupported trace format
(detected: unknown). Supported formats: flowspec-trace.json, otlp.json."


Problem 2: explore command example is missing its data file

  1. Examine the examples/nginx-exploration/ directory.
  2. Note that the run-example.sh script depends on a file named access.log.
  3. Observe that access.log does not exist in the directory or the repository.

Expected Behavior:
The examples directory should contain all necessary files to run the demos, including access.log.

Actual Behavior:
The access.log file is missing, making it impossible to run the explore command example as intended.

Recommendations

  1. Update Trace Files: Regenerate all .json trace files in the examples directory to ensure they are in a valid,
    OTel-compatible format that the current version of the CLI can parse.
  2. Provide Log File: Add the missing access.log file to the examples/nginx-exploration/ directory so the
    run-example.sh script and the explore command can be tested directly.
  3. Verify All Examples: Before closing this issue, confirm that every example script and command mentioned in the
    README.md runs successfully from a fresh clone of the repository.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocumentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions