Writing a profile

A profile names a game and describes the processes whose traffic fragcap should attribute to it. The hard case, and the one fragcap exists for, is a client that you do not start directly: you launch a platform or publisher launcher, and it starts the game. This guide writes a profile for exactly that shape. For the full list of keys, see the profile schema.

Start from the identity

Every profile opens with the schema version and the game's identity:

schema = 1

[game]
id = "eso"
name = "The Elder Scrolls Online"

The id is the slug you pass to --profile. fragcap steam profile <APP_ID> prints a starting skeleton like this for an installed Steam title, which you then edit.

Name the client stage

A stage is a process fragcap watches for. The simplest profile has one, matched by executable name:

[[stage]]
role = "client"
lifecycle = "session"
terminal = true
match = { exe = "eso.exe" }

terminal = true means the capture ends when this process exits, and a terminal stage is always session lifecycle. match here matches by the executable file name.

Disambiguate an indirectly launched client

Matching by exe alone is enough when the name is unique. It is not enough when several processes share an image name, or when you need to be sure you are capturing the client the launcher started rather than an unrelated copy. That is what descends_from is for: it matches a process whose ancestor is another stage's process.

[[stage]]
role = "launcher"
lifecycle = "transient"
match = { exe = "launcher.exe" }

[[stage]]
role = "client"
lifecycle = "session"
terminal = true
match = { exe = "game.exe", descends_from = "launcher" }

Now the client stage matches game.exe only when it descends from the process the launcher stage matched. fragcap resolves descends_from over the process tree it builds from creation-time telemetry; it never opens a handle to the target and never matches a process against itself.

Validate before you capture

fragcap profile validate ./eso.toml

Validation runs before every capture anyway, but running it directly reports every problem in one pass while you are still editing: an unknown key, a stage that matches nothing, a role named by descends_from that no stage declares. Fix all of them, then capture:

fragcap run --profile ./eso.toml --out capture.fcapng