Design Proposal: Debug expression

[sargunv]

Design Proposal: Debug expression

Motivation

When writing complex expressions, I sometimes have a logic bug and need to debug my expression. Most programming languages have some sort of "print statement debugging" trivially available to debug things even without a dedicated debugger tool. The expression system has no feature available, other than assigning some value to a SymbolLayer's text field to display it on the map.

Proposed Change

A new expression, perhaps called println or debug-log or something, that takes one or two parameters. When it's evaluated, it simply logs to stdout (native) or console (browser) whatever value it received on the first parameter, and returns that same value. If the second parameter was provided, it's a string label for the log line.

This way, the style writer can wrap any portion of an expression with println to log the output of that expression, or wrap a large expression with multiple printlns with different labels to really understand what might be going on.

It's not really intended to be used in production styles; just while developing a style.

Signature: ["println" value label?] -> value

API Modifications

^

Migration Plan and Compatibility

Nothing to migrate; fully backwards compatible.

Rejected Alternatives

• As described above but name it log: would be confusing with math expressions log10 and log2.
• No new expression; just continue using SymbolLayer text as before to get some debug output. This is unwieldy, especially if I want to log multiple values.

[HarelM]

I don't think this should be a part of the spec as you might get different results based on the support matrix of the platforms.
Having said that, I don't see a reason not to include it in the relevant platforms APIs.
But then again, if you are debugging and expecting the value to be printed somewhere you might not be a "typical" cartographer...
IDK, I'm not sure I fully understand how this will work for someone using maputnik for example...

[sargunv]

Maputnik is using Maplibre GL JS, so I guess it'll print to the browser console by default?

If Maplibre JS allows logger configuration (I think Native does) then maybe Maputnik could capture it and display it in some UI. Though that's out of scope for this proposal, and such a log UI would be useful independently (like, seeing logs of any issues loading tiles while configuring a source)

I'm not sure what it means for an expression to not be part of the spec but still supported by the SDK. I'm proposing:

• such an expression function should exist
• it should have about the same usage on JS and Native (well, the actual format of the string being printed can be different; just the way it's used should be the same)
• it should be documented, so people discover it and know how to use it

To me, that means it's a part of the spec. Though maybe we don't make backwards compatibility guarantees about it, and don't define exactly the format of the log line, and that's the differentiating factor that makes it not "part of the spec"?

[HarelM]

I meant that native and js might not support the same expressions (like "distance" for example that was added to js only recently).

There are debug elements built into in js, for example, like showTileBoundaries which is also not part of the spec, I don't see this proposal as something different, that's what I'm trying to say.

[sargunv]

Ah yeah, I don't think certain functions being unavailable on one platform or another really affects this. It'll log whatever value it receives when it's evaluated. If that value comes from a distance expression, it'll just be an error expression, the same as it was before this function.

Just like how console.log does effectively the same thing on Node vs on the browser. Some functions / packages / APIs are different between the platforms, but that doesn't really matter to console.log. It just logs what's passed to it, no matter what produced it.

[sargunv]

There are debug elements built into in js, for example, like showTileBoundaries which is also not part of the spec, I don't see this proposal as something different, that's what I'm trying to say.

Is that available via the style JSON though? I thought it's just some property that can be set in the code that manages a map view

[HarelM]

It's not available via style.json, that's my point 😀

[neodescis]

I also feel like adding this to the spec may not be the right approach. I think the ability to add some kind of expression debugging info to every feature on the map would be extremely helpful though, and more analogous to showTileBoundaries. Maybe the inputs and outputs of every statement in each property's expression tree could be made available, structured in the same way as the expression tree? Debugging info for layer filter expressions could be exposed somewhere (else) as well.

[sargunv]

It's not available via style.json, that's my point 😀

How would one use it then, if designing a style via JSON?

[sargunv]

I think the ability to add some kind of expression debugging info to every feature on the map would be extremely helpful though

I feel like that'd get pretty noisy; logging info about many hundreds of features, and still nothing about the particular expression logic I'm debugging.

It's like writing some API server and deciding not to be able to log particular data in business logic because logging every API request/response is enough.

[neodescis]

Actually, my idea was to make available every statement, and then you could easily find the one you want since the structure would match the expression in the style. That would give you the info you're asking for, albeit in a fire hose with everything else. So yes, it is potentially very "noisy." Optionally it could be configured to add to every feature, a feature with a given ID, or none (the default).

Just spitballing though!

[neodescis]

Actually, it would also be easy to make it configurable to only include some statement that you want included.

[sargunv]

I like the idea of a global firehose or filter style "log the layer property values" feature, but I think that's orthogonal to what's actually being proposed here. What I want is to log particular values inside an expression, so I can debug the logic inside, not just the final result of an expression.

Maybe it'll be more clear with a concrete example. Take this buggy expression, a simplified (single-language) version of a localized name expression. In Kotlin (maplibre-compose) it was:

switch(
  condition(
    test = all(
      feature["name_es"].asString().convertToBoolean(),
      feature["name"].asString() neq feature["name_es"].asString()
    ),
    output = feature["name"].asString() + const("\n") + feature["name_es"].asString()
  ),
  fallback = feature["name"].asString()
)

In JSON, that translates to:

["case",
	["all"
		["to-boolean", ["string", ["get", "name_es"]]],
		["!=", ["string", ["get", "name"]], ["string", ["get", "name_es"]]]
	],
	["concat", ["string", ["get", "name"]], "\n", ["string", ["get", "name"]]],
	["string", ["get", "name"]]
]

The bug here is that ["string", ["get", "name_es"]] will be an error if ["get", "name_es"] is null, so the text field didn't display any text.

Debugging that required a bunch of trial and error, but if I had the println expression, I'd be able to debug it just by instrumenting the expression with some prints:

["case",
	["println", ["all"
		["println", ["to-boolean",
			["println", ["string",
				["println", ["get", "name_es"], "GET SPANISH"]
			], "ASSERT STRING"]
		], "CONVERT TO BOOLEAN"],
		["!=", ["string", ["get", "name"]], ["string", ["get", "name_es"]]]
	], "CASE CONDITION"],
	["concat", ["string", ["get", "name"]], "\n", ["string", ["get", "name"]]],
	["string", ["get", "name"]]
]

Which might log something like:

layer=example layout.text-field: GET SPANISH: "Hamburgo"
layer=example layout.text-field: ASSERT STRING: "Hamburgo"
layer=example layout.text-field: CONVERT TO BOOLEAN: true
layer=example layout.text-field: CASE CONDITION: true
layer=example layout.text-field: GET SPANISH: null
layer=example layout.text-field: ASSERT STRING: error
layer=example layout.text-field: CONVERT TO BOOLEAN: error
layer=example layout.text-field: CASE CONDITION: error

and then immediately notice the log line labeled "STRING" is an error when the log line labeled "GET SPANISH" is null.

So ofc, the fixed expression is either replacing assertion ["string"] with coercion ["to-string"] or just removing those type assertions / conversions altogether:

["case",
	["all"
		["get", "name_es"],
		["!=", ["get", "name_es"], ["get", "name_es"]]
	],
	["concat", ["get", "name"], "\n", ["get", "name"]],
	["get", "name"]
]

which in Kotlin (maplibre-compose) is:

switch(
  condition(
    test = all(
      feature["name_es"].cast(),
      feature["name"].cast() neq feature["name_es"].cast()
    ),
    output = feature["name"].cast() + const("\n") + feature["name_es"].cast()
  ),
  fallback = feature["name"].cast()
)

Even outside of typing issues (which are probably exacerbated by maplibre compose or other strongly typed DSLs), you can imagine there could be other logic bugs in some complex math expressions, or typos in feature names, etc. And so, it's helpful to instrument within the expression to see where our expectations start to mismatch reality.

I imagine with the previously described global firehose of logging expression evaluations, I'd just get some log line like:

layer=example layout.text-field: "Hamburg\nHamburgo"
layer=example layout.text-field: error

which might be helpful in some scenarios but won't really help debug inside large, complex, expressions.

[sargunv]

and well, I'm still not clear what it means for this to be part of the API but not part of the spec. I guess all I'm proposing is:

• The println expression is added in maplibre js and maplibre native (I'd be happy to implement and PR)
• It takes the same parameters and has roughly similar functionality on both, though the exact log format and destination may be different
• It's documented somewhere (if that's not on this page, that's fine, though I'm unsure why we wouldn't put it with all the other functions)

If that means it's part of the spec, then I'm proposing it be part of the spec. If "part of the spec" means something more, then I guess I'm not proposing it be part of the spec.

[HarelM]

Part of the API means you could do something like: map.printExpressionEvaluationForLayer(myLayerId) and get what you described.
I would first consider adding this in the relevant platform and if this is helpful and people want to add it to the spec, only then continue here.

The argument here about printing all the features in the screen at the same time is a valid concern from a feature perspective related to this design proposal.
It is a problem also in the above API suggestion, too.

I've added console.log as part of my maintenance of maplibre and when it comes to styles, features, etc it's almost never helpful due to the fact that evaluation happens a lot of times with regards to rendering...

[sargunv]

Are you proposing I'd pass some expression to a function on the map? So something like, map.evaluateExpression(expression, feature) -> value, and I could then console.log that value? That'd work too, though then other style editing tools like Maputnik would also need to add explicit support for it rather than getting it by default in devtools.