Flow Span

Flow Span is how Fieldpine record the internal tracing of functions and actions being executed. They provide a programmer controlled way of collecting trace information. FlowSpans are multi thread aware, and a flow span contains the "flow", ie path taken through the code, for a function or task, not the overall order within the complete program

A FlowSpan records that precise path and logic decisions made for a single task. For example, if a user scans a barcode, what exact steps where taken.

A FlowPoint is an integer that is placed into the code and acts as a line number. While we could use preprocessor symbols like __LINE__ or __FUNCNAME__, these can either change over different versions, or result in very large code output. Flowpoints are stored in a reference database

How FlowSpan is Captured

Internally the programming code creates flow span blocks, and writes messages to those blocks.

FlowSpan CmdSpan(987654);       // Create a trace span on the stack for this thread.  987654 is the flowpoint

if (something == 1) {
    FlowSpan::Flow(1234);       // Record a flowpoint into the current flow span
} else {
    FlowSpan::Flow(1235, "something", something);   // Record a flow point with optional data
}

While not clear in the example above, FlowSpan::Flow() finds the current flowSpan, if any, and writes to that. Programmers can simply add Flow() calls in suitable places and not worry about wheather tracing is active.

FlowSpan Structure

Flowspans are typically stored in a JSON object, with the following fields:

• fp - Flowpoint generating this span
• th - Thread Id
• seq - Internal sequence number. Increased as each flow span is created
• ds - Date start of when this flow span began
• de - Date when flow span ended
• lines - An array of trace lines. These can be
  • An integer, which should be a flowpoint
  • A string, which is a simple trace message
  • An object, which contains a block of data, such as variables or indepth details.

  There is no defined rules as to what can be put into the lines array, however many places will insert common information such as source code function names and line numbers

{
  "fp": 1800251218,
  "th": 3800,
  "seq": 6,
  "ds": "2026-01-04 09:31.48",
  "lines": [
    {
      "func": "long __cdecl PosCommands::RunCommandString(const char *,class UIScreenContext *,class FPVar2 *)",
      "ln": 1019
    },
    { "cmd": "maint(pull(when(notexist,richardte.png) url(www.fieldpine.com/geni/clipart_676.png) output(richardte.png) nozip) )" }
  ],
  "de": "2026-01-04 09:31.48"
}

Viewing FlowSpan

1. On PosGreen, in the Pos run folder, a file called DebugFlowSpan_NNNNN.json is created every few seconds containing known FlowSpans. NNNN is the current process id. The easiest way to find the current file in use is to sort by modified date in Windows Explorer.
2. On PosGreen, browse to the control url and FlowSpans and reportable errors are shown in the menu. http://localhost:8095/fdlmgmt/default.htm

To have PosGreen send flowSpans and flowErrors to external monitoring services, create a setting in fpos.ctl as follows

multi:force:RemoteServer.YOUR-NAME.Control={
	"url": "https://example.com/my-endpoint",
	"httpheaders": [ "x-api-key: key-if-needed", "authorization: Bearer ...." ],
	"flowerror_want": [ "all" ],
	"flowerror_exclude": [ 12345 ],
	"flowspan_want": [ 2100260103 ]
}
    *** Note, a blank line is required here to end the multi:force

To Send to your Fieldpine Ingest account, use the following

multi:force:RemoteServer.ToMyIngest.Control={
	"url": "fieldpine.ingest",
	"flowerror_want": [ "all" ],
	"flowspan_want": [ ... any required ... ],
    "tuev_want": "all"
}
    *** Note, a blank line is required here to end the multi:force

When using a remote server, you can request all flowspans are sent using "flowspan_want": "all", but this will slow your system down noticeably due to the volume and size each span