Troubleshooting

Learn how to troubleshoot problems for self-hosted installations of the Timefold Platform. Self-hosted installations don’t include a UI to help with troubleshooting, but expose multiple APIs to help you find the problem.

Troubleshoot a Model Run execution

In certain scenarios solving a model run can end with unexpected result. For instance:

  • A failed run.

  • A run that has an unexpected solution.

  • A run with validation errors.

  • Other unexpected scenarios.

Important information is stored on the platform as part of the run to help you troubleshoot any issues:

  • Input request: the exact input that was provided to the platform.

  • Configuration: final configuration (run and model) used when solving.

  • Logs: collected logs during solving.

  • Output: the solution provided after run completion.

  • Platform logs: optionally platform logs that are relevant to this run.

Collect information via script

The section below provides a complete script that can be executed on unix like systems.

This script expects following environment variables:

The run identifier is provided as an argument to the script.

Extract run info script
#!/bin/bash

# Script to collect run information for troubleshooting
# single argument is required - run id
# collects:
# - model api details like output, logs, configuration and request input
# - if kubernetes client (kubectl is available) platform logs related to the run - to be able to collect information from kubernetes login first into the cluster
#
# Required environment variables
# API_KEY - api key to be used to call the platform apis
# PLATFORM_URL - url of the platform to be called e.g. https://app.timefold.ai/api/models/employee-scheduling/v1/schedules
# NAMESPACE - kubernetes namespace to be used when retrieving platform logs - only needed when kubectl is available


if [ -z "$API_KEY" ]
  then
    echo "No API KEY set. Set environment variable 'API_KEY' with your Timefold platform API key before running this script"
    exit 0
fi

if [ -z "$PLATFORM_URL" ]
  then
    echo "No PLATFORM_URL set. Set environment variable 'PLATFORM_URL' with your Timefold platform url e.g. https://app.timefold.ai/api/models/employee-scheduling/v1/schedules"
    exit 0
fi

if [ -z "$1" ]
  then
    echo "No run id supplied"
    exit 0
fi

RUN_ID=$1
SUCESS_RESPONSE=200

RUN_EXISTS=$(curl -s -I -w "%{http_code}" $PLATFORM_URL'/'$RUN_ID -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o /dev/null)

if [ "$RUN_EXISTS" != "$SUCESS_RESPONSE" ]
  then
    echo "No run found in the system with id: "$RUN_ID
    exit 0
fi

echo "Collecting output of the run with id "$RUNID" into folder"$(pwd)"/"$RUN_ID

# extract base url to be able to invoke none model endpoints e.g. /api/info
[[ $PLATFORM_URL =~ ^https?://[^/]+ ]]
BASE_URL="${BASH_REMATCH[0]}"


mkdir -p $RUN_ID
echo "Collecting platform info"
curl -s -X 'GET' $BASE_URL'/api/info' -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o $RUN_ID/info.json
echo "Collecting output of the run"
curl -s -X 'GET' $PLATFORM_URL'/'$RUN_ID -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o $RUN_ID/output.json
echo "Collecting configuration of the run"
curl -s -X 'GET' $PLATFORM_URL'/'$RUN_ID'/config' -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o $RUN_ID/config.json
echo "Collecting logs of the run"
curl -s -X 'GET' $PLATFORM_URL'/'$RUN_ID'/logs' -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o $RUN_ID/logs.json
echo "Collecting model request of the run"
curl -s -X 'GET' $PLATFORM_URL'/'$RUN_ID'/model-request' -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o $RUN_ID/model-request.json


if [ -n "$NAMESPACE" ]
  then
    echo "Collecting logs from platform pods in namespace "$NAMESPACE
    kubectl -n $NAMESPACE logs -l ai.timefold/platform-gateway=true --tail -1 | grep $RUN_ID > $RUN_ID/platform-logs.txt

fi

if ! command -v zip 2>&1 >/dev/null
then
    exit 0
fi

zip -q $RUN_ID.zip $RUN_ID/*
echo "Collected all information, complete package available as "$RUN_ID.zip" that can be shared with Timefold support"

Save the script to a file called extract-run-info.sh (assign executable rights to it chmod +x extract-run-info.sh) and export the environment variables below.

export PLATFORM_URL=https://app.timefold.ai/api/models/employee-scheduling/v1/schedules
export API_KEY=YOUR_API_KEY
export NAMESPACE=timefold
The values above are examples only, replace them with the actual values from your environment. 
./extractrun-info.sh RUN_ID

Collect individual parts manually

Most of the information you need can be collected using the platform APIs (except platform logs that require access to Kubernetes cluster).

The following curl commands extract this information. The following environment variables are required to execute the commands:

Extract run output
curl -s -X 'GET' $PLATFORM_URL'/'$RUN_ID -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o $RUN_ID/output.json
Extract run configuration
curl -s -X 'GET' $PLATFORM_URL'/'$RUN_ID'/config' -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o $RUN_ID/config.json
Extract run logs
curl -s -X 'GET' $PLATFORM_URL'/'$RUN_ID'/logs' -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o $RUN_ID/logs.json
Extract run request
curl -s -X 'GET' $PLATFORM_URL'/'$RUN_ID'/model-request' -H 'accept: application/json' -H 'X-API-KEY: '$API_KEY -o $RUN_ID/model-request.json

If you are unable to identify the issue, the information you have collected will help Timefold Support assist you.

Verify platform & model versions

When troubleshooting, it’s important to be aware of the version of the Timefold Platform you are running, and the version of the model you have installed on the platform.

You can verify the platform and model version information from the result of the /api/info endpoint.

You can then cross-check with our changelog and documentation site to see if the problem might be related to differences between versions.