https://github.com/karmakrafts/introspekt
Positional code and compile-time introspection API for Kotlin/Multiplatform.
https://github.com/karmakrafts/introspekt
compiler-plugin introspection kotlin kotlin-common kotlin-compiler kotlin-compiler-plugin kotlin-js kotlin-jvm kotlin-native trace tracing
Last synced: 11 months ago
JSON representation
Positional code and compile-time introspection API for Kotlin/Multiplatform.
- Host: GitHub
- URL: https://github.com/karmakrafts/introspekt
- Owner: karmakrafts
- License: apache-2.0
- Created: 2025-04-20T23:19:27.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-07-08T05:19:01.000Z (12 months ago)
- Last Synced: 2025-07-08T06:36:47.598Z (12 months ago)
- Topics: compiler-plugin, introspection, kotlin, kotlin-common, kotlin-compiler, kotlin-compiler-plugin, kotlin-js, kotlin-jvm, kotlin-native, trace, tracing
- Language: Kotlin
- Homepage: https://git.karmakrafts.dev/kk/introspekt
- Size: 675 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Introspekt
[](https://git.karmakrafts.dev/kk/introspekt/-/pipelines)
[](https://git.karmakrafts.dev/kk/introspekt/-/packages)
[](https://git.karmakrafts.dev/kk/introspekt/-/packages)
Introspekt is a positional code API and introspection framework for Kotlin Multiplatform.
It currently adds the following features:
* `SourceLocation` type with access to module name, file path, function name, line and column
* `FunctionInfo` type for introspecting current/caller function signature and location
* `ClassInfo` type for introspecting current/caller classes including functions
* `AnnotationUsageInfo` type for introspecting annotation types and their parameters
* `TypeInfo` type for fundamental RTTI integrated with **kotlin.reflect** to fix gaps on Kotlin/JS and other platforms
* Default-parameter inlining for intrinsic types listed above (like `std::source_location` in C++)
* Compile-time evaluation of location hashes to improve runtime performance for positional memoization
* Tracing API for automatically injecting trace callbacks into code, including manual spans and events
### How to use it
First, add the official Maven Central repository to your `settings.gradle.kts`:
```kotlin
pluginManagement {
repositories {
maven("https://central.sonatype.com/repository/maven-snapshots")
mavenCentral()
}
}
dependencyResolutionManagement {
repositories {
maven("https://central.sonatype.com/repository/maven-snapshots")
mavenCentral()
}
}
```
Then add a dependency on the plugin in your root buildscript:
```kotlin
plugins {
id("dev.karmakrafts.introspekt.introspekt-gradle-plugin") version ""
}
kotlin {
sourceSets {
commonMain {
dependencies {
implementation("dev.karmakrafts.introspekt:introspekt-runtime:")
}
}
}
}
```
### Tracing
Tracing can be used to automatically inject callbacks into the code to collect certain events.
The events can be processed/collected using an implementation of `TraceCollector`.
The following example illustrates a simple use-case for logging:
```kotlin
object MyCollector : TraceCollector {
private val logger: MyLogger = MyLogger() // Some logger from another library
fun enterSpan(span: TraceSpan) = logger.trace("Entering span ${span.name}")
fun leaveSpan(span: TraceSpan, end: SourceLocation) = logger.trace("Leaving span ${span.name}")
fun enterFunction(function: FunctionInfo) { /* ... */ }
fun leaveFunction(function: FunctionInfo) { /* ... */ }
fun call(callee: FunctionInfo, caller: FunctionInfo, location: SourceLocation) { /* ... */ }
fun event(event: TraceEvent) { /* ... */ }
}
fun main() {
// Register the collector before any code we want to trace is executed
TraceCollector.register(MyCollector)
// Enter code we want to trace
functionIWantToTrace()
}
@Trace // This will inject callbacks after every call, and when entering/leaving functions
fun functionIWantToTrace() {
TraceSpan.enter("My awesome span")
// ...
TraceSpan.leave()
// ...
}
```