Troubleshooting

Troubleshoot a run execution

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

A failed run.
A run that has 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.

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

This script expects following environment variables:

PLATFORM_URL: the URL to the platform, e.g. https://app.timefold.ai/api/models/employee-scheduling/v1/schedules.
API_KEY: the API key used to call models API.
NAMESPACE: the Kubernetes namespace where Timefold platform is installed.

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"
    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

mkdir -p $RUN_ID
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:

RUN_ID: unique identifier of the run.
PLATFORM_URL URL to the platform, e.g. https://app.timefold.ai/api/models/employee-scheduling/v1/schedules.
API_KEY: The API key used to call models API.

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.