feat(trace): Add API for trace reading

This change introduces a new OpenDC API for reading various trace
formats in a streaming manner.

10 files changed, 591 insertions, 0 deletions

diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/ResourceColumns.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/ResourceColumns.kt
new file mode 100644
index 00000000..65055762
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/ResourceColumns.kt
@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+@file:JvmName("ResourceColumns")
+package org.opendc.trace
+
+/**
+ * Identifier of the resource.
+ */
+public val RESOURCE_ID: TableColumn<String> = stringColumn("resource:id")
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/ResourceStateColumns.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/ResourceStateColumns.kt
new file mode 100644
index 00000000..17f52ab6
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/ResourceStateColumns.kt
@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+@file:JvmName("ResourceStateColumns")
+package org.opendc.trace
+
+import java.time.Instant
+
+/**
+ * Identifier of the resource.
+ */
+public val RESOURCE_STATE_ID: TableColumn<String> = stringColumn("resource_state:id")
+
+/**
+ * Timestamp for the state.
+ */
+public val RESOURCE_STATE_TIMESTAMP: TableColumn<Instant> = TableColumn("resource_state:timestamp", Instant::class.java)
+
+/**
+ * Number of CPUs for the resource.
+ */
+public val RESOURCE_STATE_NCPUS: TableColumn<Int> = intColumn("resource_state:ncpus")
+
+/**
+ * Total CPU capacity of the resource in MHz.
+ */
+public val RESOURCE_STATE_CPU_CAPACITY: TableColumn<Double> = doubleColumn("resource_state:cpu_capacity")
+
+/**
+ * Total CPU usage of the resource in MHz.
+ */
+public val RESOURCE_STATE_CPU_USAGE: TableColumn<Double> = doubleColumn("resource_state:cpu_usage")
+
+/**
+ * Total CPU usage of the resource in percentage.
+ */
+public val RESOURCE_STATE_CPU_USAGE_PCT: TableColumn<Double> = doubleColumn("resource_state:cpu_usage_pct")
+
+/**
+ * Memory capacity of the resource in KB.
+ */
+public val RESOURCE_STATE_MEM_CAPACITY: TableColumn<Double> = doubleColumn("resource_state:mem_capacity")
+
+/**
+ * Memory usage of the resource in KB.
+ */
+public val RESOURCE_STATE_MEM_USAGE: TableColumn<Double> = doubleColumn("resource_state:mem_usage")
+
+/**
+ * Disk read throughput of the resource in KB/s.
+ */
+public val RESOURCE_STATE_DISK_READ: TableColumn<Double> = doubleColumn("resource_state:disk_read")
+
+/**
+ * Disk write throughput of the resource in KB/s.
+ */
+public val RESOURCE_STATE_DISK_WRITE: TableColumn<Double> = doubleColumn("resource_state:disk_write")
+
+/**
+ * Network receive throughput of the resource in KB/s.
+ */
+public val RESOURCE_STATE_NET_RX: TableColumn<Double> = doubleColumn("resource_state:net_rx")
+
+/**
+ * Network transmit throughput of the resource in KB/s.
+ */
+public val RESOURCE_STATE_NET_TX: TableColumn<Double> = doubleColumn("resource_state:net_tx")
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/Table.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/Table.kt
new file mode 100644
index 00000000..11e5d6b7
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/Table.kt
@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.opendc.trace
+
+/**
+ * A table is collection of rows consisting of typed columns.
+ */
+public interface Table {
+    /**
+     * The name of the table.
+     */
+    public val name: String
+
+    /**
+     * A flag to indicate that the table is synthetic (derived from another table).
+     */
+    public val isSynthetic: Boolean
+
+    /**
+     * Determine whether the specified [column] is supported by this table.
+     */
+    public fun isSupported(column: TableColumn<*>): Boolean
+
+    /**
+     * Open a [TableReader] for this table.
+     */
+    public fun newReader(): TableReader
+
+    /**
+     * Open a [TableReader] for [partition] of the table.
+     */
+    public fun newReader(partition: String): TableReader
+}
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableColumn.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableColumn.kt
new file mode 100644
index 00000000..247e7312
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableColumn.kt
@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.opendc.trace
+
+import java.util.*
+
+/**
+ * A column in a trace table.
+ *
+ * @param name The universal name of this column.
+ */
+public class TableColumn<out T>(public val name: String, type: Class<T>) {
+    /**
+     * The type of the column.
+     */
+    private val type: Class<*> = type
+
+    /**
+     * Determine whether the type of the column is a subtype of [column].
+     */
+    public fun isAssignableTo(column: TableColumn<*>): Boolean {
+        return type.isAssignableFrom(column.type)
+    }
+
+    /**
+     * Compute a hash code for this column.
+     */
+    public override fun hashCode(): Int = Objects.hash(name, type)
+
+    /**
+     * Determine whether this column is equal to [other].
+     */
+    public override fun equals(other: Any?): Boolean = other is TableColumn<*> && name == other.name && type == other.type
+
+    /**
+     * Return a string representation of this column.
+     */
+    public override fun toString(): String = "TableColumn[$name,$type]"
+}
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableColumns.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableColumns.kt
new file mode 100644
index 00000000..64920498
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableColumns.kt
@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+@file:JvmName("TableColumns")
+package org.opendc.trace
+
+/**
+ * Construct a [TableColumn] with [Any] type.
+ */
+public fun objectColumn(name: String): TableColumn<Any> = TableColumn(name, Any::class.java)
+
+/**
+ * Construct a [TableColumn] with a [String] type.
+ */
+public fun stringColumn(name: String): TableColumn<String> = TableColumn(name, String::class.java)
+
+/**
+ * Construct a [TableColumn] with a [Number] type.
+ */
+public fun numberColumn(name: String): TableColumn<Number> = TableColumn(name, Number::class.java)
+
+/**
+ * Construct a [TableColumn] with an [Int] type.
+ */
+public fun intColumn(name: String): TableColumn<Int> = TableColumn(name, Int::class.java)
+
+/**
+ * Construct a [TableColumn] with a [Long] type.
+ */
+public fun longColumn(name: String): TableColumn<Long> = TableColumn(name, Long::class.java)
+
+/**
+ * Construct a [TableColumn] with a [Double] type.
+ */
+public fun doubleColumn(name: String): TableColumn<Double> = TableColumn(name, Double::class.java)
+
+/**
+ * Construct a [TableColumn] with a [Boolean] type.
+ */
+public fun booleanColumn(name: String): TableColumn<Boolean> = TableColumn(name, Boolean::class.java)
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableReader.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableReader.kt
new file mode 100644
index 00000000..b5e7669f
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableReader.kt
@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.opendc.trace
+
+/**
+ * Base class for reading entities from a workload trace table in streaming fashion.
+ */
+public interface TableReader : AutoCloseable {
+    /**
+     * Advance the stream until the next row is reached.
+     *
+     * @return `true` if the row is valid, `false` if there are no more rows.
+     */
+    public fun nextRow(): Boolean
+
+    /**
+     * Determine whether the [TableReader] supports the specified [column].
+     */
+    public fun hasColumn(column: TableColumn<*>): Boolean
+
+    /**
+     * Obtain the value of the current column with type [T].
+     */
+    public fun <T> get(column: TableColumn<T>): T
+
+    /**
+     * Read the specified [column] as boolean.
+     */
+    public fun getBoolean(column: TableColumn<Boolean>): Boolean
+
+    /**
+     * Read the specified [column] as integer.
+     */
+    public fun getInt(column: TableColumn<Int>): Int
+
+    /**
+     * Read the specified [column] as long.
+     */
+    public fun getLong(column: TableColumn<Long>): Long
+
+    /**
+     * Read the specified [column] as double.
+     */
+    public fun getDouble(column: TableColumn<Double>): Double
+
+    /**
+     * Closes the reader so that no further iteration or data access can be made.
+     */
+    public override fun close()
+}
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/Tables.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/Tables.kt
new file mode 100644
index 00000000..bb9d93e2
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/Tables.kt
@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+@file:JvmName("Tables")
+package org.opendc.trace
+
+/**
+ * A table containing all workflows in a workload.
+ */
+public const val TABLE_WORKFLOWS: String = "workflows"
+
+/**
+ * A table containing all tasks in a workload.
+ */
+public const val TABLE_TASKS: String = "tasks"
+
+/**
+ * A table containing all resources in a workload.
+ */
+public const val TABLE_RESOURCES: String = "resources"
+
+/**
+ * A table containing all resource states in a workload.
+ */
+public const val TABLE_RESOURCE_STATES: String = "resource_states"
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TaskColumns.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TaskColumns.kt
new file mode 100644
index 00000000..5d3143ff
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TaskColumns.kt
@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+@file:JvmName("TaskColumns")
+package org.opendc.trace
+
+/**
+ * A column containing the task identifier.
+ */
+public val TASK_ID: TableColumn<Long> = longColumn("task:id")
+
+/**
+ * A column containing the identifier of the workflow.
+ */
+public val TASK_WORKFLOW_ID: TableColumn<Long> = longColumn("task:workflow_id")
+
+/**
+ * A column containing the submit time of the task.
+ */
+public val TASK_SUBMIT_TIME: TableColumn<Long> = longColumn("task:submit_time")
+
+/**
+ * A column containing the wait time of the task.
+ */
+public val TASK_WAIT_TIME: TableColumn<Long> = longColumn("task:wait_time")
+
+/**
+ * A column containing the runtime time of the task.
+ */
+public val TASK_RUNTIME: TableColumn<Long> = longColumn("task:runtime")
+
+/**
+ * A column containing the parents of a task.
+ */
+@Suppress("UNCHECKED_CAST")
+public val TASK_PARENTS: TableColumn<Set<Long>> = TableColumn("task:parents", type = Set::class.java as Class<Set<Long>>)
+
+/**
+ * A column containing the children of a task.
+ */
+@Suppress("UNCHECKED_CAST")
+public val TASK_CHILDREN: TableColumn<Set<Long>> = TableColumn("task:children", type = Set::class.java as Class<Set<Long>>)
+
+/**
+ * A column containing the requested CPUs of a task.
+ */
+public val TASK_REQ_NCPUS: TableColumn<Int> = intColumn("task:req_ncpus")
+
+/**
+ * A column containing the allocated CPUs of a task.
+ */
+public val TASK_ALLOC_NCPUS: TableColumn<Int> = intColumn("task:alloc_ncpus")
+
+/**
+ * A column containing the status of a task.
+ */
+public val TASK_STATUS: TableColumn<Int> = intColumn("task:status")
+
+/**
+ * A column containing the group id of a task.
+ */
+public val TASK_GROUP_ID: TableColumn<Int> = intColumn("task:group_id")
+
+/**
+ * A column containing the user id of a task.
+ */
+public val TASK_USER_ID: TableColumn<Int> = intColumn("task:user_id")
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/Trace.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/Trace.kt
new file mode 100644
index 00000000..36e93b52
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/Trace.kt
@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.opendc.trace
+
+/**
+ * A trace is a collection of related tables that characterize a workload.
+ */
+public interface Trace {
+    /**
+     * The list of table names in the workload trace.
+     */
+    public val tables: List<String>
+
+    /**
+     * Determine if the trace contains a table with the specified [name].
+     */
+    public fun containsTable(name: String): Boolean
+
+    /**
+     * Obtain a [Table] with the specified [name].
+     */
+    public fun getTable(name: String): Table?
+}
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/spi/TraceFormat.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/spi/TraceFormat.kt
new file mode 100644
index 00000000..54029fcf
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/spi/TraceFormat.kt
@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.opendc.trace.spi
+
+import org.opendc.trace.Trace
+import java.net.URL
+import java.util.*
+
+/**
+ * A service-provider class for parsing trace formats.
+ */
+public interface TraceFormat {
+    /**
+     * The name of the trace format.
+     */
+    public val name: String
+
+    /**
+     * Open a new [Trace] with this provider.
+     *
+     * @param url A reference to the trace.
+     */
+    public fun open(url: URL): Trace
+
+    /**
+     * A helper object for resolving providers.
+     */
+    public companion object {
+        /**
+         * A list of [TraceFormat] that are available on this system.
+         */
+        public val installedProviders: List<TraceFormat> by lazy {
+            val loader = ServiceLoader.load(TraceFormat::class.java)
+            loader.toList()
+        }
+
+        /**
+         * Obtain a [TraceFormat] implementation by [name].
+         */
+        public fun byName(name: String): TraceFormat? = installedProviders.find { it.name == name }
+    }
+}