PromQL-like Syntax for Advanced Queries / Automation

[sf1tzp]

First off, this is kind of a large request - and I just want to share the idea with you. I have not started working on this, just thinking about it. Please let me know what you think. Thank you for making the project, I like using it!

Background:
I can't help but notice similarities between Traggo's and Prometheus' data models. If you've never used Prometheus before, it uses a key-value system (called "labels") to mark point-in-time metrics.

Prometheus has a query language (called "PromQL") which allows you to describe various aspects of system behavior based on your labels. This technology underpins others like Grafana, Autoscalers, etc.

For example, you can define a query cpu_usage_total{host="production",region="eu-central"}[10m] > 0.9, whose result is true when CPU usage has been higher than 90% for 10 minutes. Prometheus will monitor this condition and can be configured to do something (send a message in slack, or post an HTTP request to an autoscaler service, etc).

Describe the solution you'd like
I think adding a similar capability to Traggo would enable some cool workflows:

• Proactive Time Management / Notifications:
  • Example: Notify me if I've spent too much time working for a specific client this weeksum{client:a}[1w] > 40h
  • Example: A dashboard panel which tells me if I've spent enough time studying this month sum{task:study,subject:deutsch}[1m] < 12h
• Automatic Invoicing or other Integrations
  • Example: Aggregate the time spans for Client A's projects sum by project {client:a}[1w]

Describe alternatives you've considered

I arrived here by considering ways to integrate Traggo with my invoicing software. I saw #67, but there is no documentation on the GraphQL API as of yet (on https://traggo.net/ at least). So I am considering building my own integration using SQL exports, but I think many people have this issue, and adding this kind of query capability to Traggo would be a nice UX.

Additional context

Traggo has a few open issues which could be resolved with such a query syntax:

#67
#178
#203
#227

[jmattheis]

I think all your examples should be covered via the stats endpoint. You can find the graphql schema here https://github.com/traggo/server/blob/master/schema.graphql this is basically a documentation for every field and field type. If you've traggo running you can open yourdomain.com/graphql for an interactive graphql editor.

Example: Notify me if I've spent too much time working for a specific client this weeksum{client:a}[1w] > 40h

Can be achieved with the stats endpoint. E.g.

Login:

$ jq -c -n --arg Q '
mutation {
  login(username: "admin" pass: "admin" deviceName: "api" type: NoExpiry cookie: false) {
    token
  }
}' '{"query":$Q}' | curl 'http://localhost:3030/graphql' -X POST -d@- -H 'content-type: application/json'

{"data":{"login":{"token":"GJvvIG0OYO6zNflcAYGp"}}}

jq -c -n --arg Q '
{
  stats(
    tags: ["client"]
    ranges: [{start: "2026-01-01T00:00:00Z", end: "2026-01-31T23:23:59Z"}],
    requireTags: [{key: "client", value: "a"}]
  ) {
    start
    end
    entries {
      key
      value
      timeSpendInSeconds
    }
  }
}' '{"query":$Q}' | curl 'http://localhost:3030/graphql' -X POST -d@- -H 'content-type: application/json' -H 'Authorization: traggo GJvvIG0OYO6zNflcAYGp'

{
  "data": {
    "stats": [
      {
        "start": "2026-01-01T00:00:00Z",
        "end": "2026-01-31T23:23:59Z",
        "entries": [
          {
            "key": "client",
            "value": "a",
            "timeSpendInSeconds": 530640
          }
        ]
      }
    ]
  }
}

Example: A dashboard panel which tells me if I've spent enough time studying this month sum{task:study,subject:deutsch}[1m] < 12h

Here you'd either group by task or subject and then specify two requires

  stats(
    tags: ["task"]
    ranges: [{start: "2026-01-01T00:00:00Z", end: "2026-01-31T23:23:59Z"}],
    requireTags: [{key: "task", value: "study"}, {key: "subject", value: "deutsch"}]
  ) 

Example: Aggregate the time spans for Client A's projects sum by project {client:a}[1w]

  stats(
    tags: ["project"]
    ranges: [{start: "2026-01-01T00:00:00Z", end: "2026-01-31T23:23:59Z"}],
    requireTags: [{key: "client", value: "a"}]
  )