Skip to content

Commit

Permalink
Streamline kotlin onboarding docs (#57342)
Browse files Browse the repository at this point in the history 
Last missing piece to close
getsentry/sentry-java#2885

Move performance into "Next Steps", Use SAGP and Maven plugin, enable
Source Context
  • Loading branch information
@adinauer
adinauer committed Oct 9, 2023
1 parent 714fabf commit a562057
Show file tree
Hide file tree
Showing 2 changed files with 159 additions and 65 deletions.
4 changes: 2 additions & 2 deletions static/app/gettingStartedDocs/java/java.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -241,10 +241,10 @@ sentry {
additionalInfo: (
<p>
{tct(
'To upload your source code to Sentry so it can be shown in stack traces, please refer to [link:Manually Uploading Source Context].',
'If you prefer to manually upload your source code to Sentry, please refer to [link:Manually Uploading Source Context].',
{
link: (
<ExternalLink href="https://docs.sentry.io/platforms/java/source-context/" />
<ExternalLink href="https://docs.sentry.io/platforms/java/source-context/#manually-uploading-source-context" />
),
}
)}
Expand Down
220 changes: 157 additions & 63 deletions static/app/gettingStartedDocs/kotlin/kotlin.tsx
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import {Fragment} from 'react';

import ExternalLink from 'sentry/components/links/externalLink';
import Link from 'sentry/components/links/link';
import {Layout, LayoutProps} from 'sentry/components/onboarding/gettingStartedDoc/layout';
import {ModuleProps} from 'sentry/components/onboarding/gettingStartedDoc/sdkDocumentation';
import {StepType} from 'sentry/components/onboarding/gettingStartedDoc/step';
Expand All @@ -22,10 +23,17 @@ interface StepsParams {
dsn: string;
hasPerformance: boolean;
packageManager: PackageManager;
organizationSlug?: string;
projectSlug?: string;
sourcePackageRegistries?: ModuleProps['sourcePackageRegistries'];
}

// Configuration Start
const packageManagerName: Record<PackageManager, string> = {
[PackageManager.GRADLE]: 'Gradle',
[PackageManager.MAVEN]: 'Maven',
};

const platformOptions: Record<PlaformOptionKey, PlatformOption> = {
packageManager: {
label: t('Package Manager'),
Expand All @@ -44,7 +52,7 @@ const platformOptions: Record<PlaformOptionKey, PlatformOption> = {
const introduction = (
<p>
{tct(
"Sentry supports Kotlin for both JVM and [Android. This wizard guides you through set up in the JVM scenario. If you're interested in [strong:Android], head over to the [gettingStartedWithAndroidLink:Getting Started] for that SDK instead. At its core, Sentry for Java provides a raw client for sending events to Sentry. If you use [strong:Spring Boot, Spring, Logback, JUL, or Log4j2], head over to our [gettingStartedWithJavaLink:Getting Started for Sentry Java].",
"Sentry supports Kotlin for both JVM and Android. This wizard guides you through set up in the JVM scenario. If you're interested in [strong:Android], head over to the [gettingStartedWithAndroidLink:Getting Started] for that SDK instead. At its core, Sentry for Java provides a raw client for sending events to Sentry. If you use [strong2:Spring Boot, Spring, Logback, JUL, or Log4j2], head over to our [gettingStartedWithJavaLink:Getting Started for Sentry Java].",
{
gettingStartedWithAndroidLink: (
<ExternalLink href="https://docs.sentry.io/platforms/android/" />
Expand All @@ -53,6 +61,7 @@ const introduction = (
<ExternalLink href="https://docs.sentry.io/platforms/java/" />
),
strong: <strong />,
strong2: <strong />,
}
)}
</p>
Expand All @@ -63,62 +72,163 @@ export const steps = ({
sourcePackageRegistries,
hasPerformance,
packageManager,
projectSlug,
organizationSlug,
}: StepsParams): LayoutProps['steps'] => [
{
type: StepType.INSTALL,
configurations:
packageManager === PackageManager.GRADLE
description: t(`Install the SDK via %s:`, packageManagerName[packageManager]),
configurations: [
{
description: (
<p>
{tct(
'To see source context in Sentry, you have to generate an auth token by visiting the [link:Organization Auth Tokens] settings. You can then set the token as an environment variable that is used by the build plugins.',
{
link: <Link to="/settings/auth-tokens/" />,
}
)}
</p>
),
language: 'bash',
code: `SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___`,
},
...(packageManager === PackageManager.GRADLE
? [
{
language: 'groovy',
partialLoading: sourcePackageRegistries?.isLoading,
description: (
<p>
{tct('Add the Sentry SDK to your [code:build.gradle] file:', {
code: <code />,
})}
{tct(
'The [link:Sentry Gradle Plugin] automatically installs the Sentry SDK as well as available integrations for your dependencies. Add the following to your [code:build.gradle] file:',
{
code: <code />,
link: (
<ExternalLink href="https://github.com/getsentry/sentry-android-gradle-plugin" />
),
}
)}
</p>
),
partialLoading: sourcePackageRegistries?.isLoading,
code: `
// Make sure mavenCentral is there.
repositories {
mavenCentral()
buildscript {
repositories {
mavenCentral()
}
}
dependencies {
implementation 'io.sentry:sentry:${
plugins {
id "io.sentry.jvm.gradle" version "${
sourcePackageRegistries?.isLoading
? t('\u2026loading')
: sourcePackageRegistries?.data?.['sentry.java']?.version ?? '4.0.0'
}'
: sourcePackageRegistries?.data?.['sentry.java.android.gradle-plugin']?.version ??
'3.12.0'
}"
}
sentry {
// Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry.
// This enables source context, allowing you to see your source
// code as part of your stack traces in Sentry.
includeSourceContext = true
org = "${organizationSlug}"
projectName = "${projectSlug}"
authToken = System.getenv("SENTRY_AUTH_TOKEN")
}
`,
},
]
: [
: []),
...(packageManager === PackageManager.MAVEN
? [
{
language: 'xml',
partialLoading: sourcePackageRegistries?.isLoading,
description: (
<p>
{tct('Add the Sentry SDK to your [code:pom.xml] file:', {
code: <code />,
})}
</p>
),
code: `
configurations: [
{
language: 'xml',
partialLoading: sourcePackageRegistries?.isLoading,
code: `
<dependency>
<groupId>io.sentry</groupId>
<artifactId>sentry</artifactId>
<version>${
sourcePackageRegistries?.isLoading
? t('\u2026loading')
: sourcePackageRegistries?.data?.['sentry.java']?.version ?? '6.25.0'
: sourcePackageRegistries?.data?.['sentry.java']?.version ?? '6.27.0'
}</version>
</dependency>
`,
`,
},
{
language: 'xml',
partialLoading: sourcePackageRegistries?.isLoading,
description: t(
'To upload your source code to Sentry so it can be shown in stack traces, use our Maven plugin.'
),
code: `
<build>
<plugins>
<plugin>
<groupId>io.sentry</groupId>
<artifactId>sentry-maven-plugin</artifactId>
<version>${
sourcePackageRegistries?.isLoading
? t('\u2026loading')
: sourcePackageRegistries?.data?.['sentry.java.mavenplugin']?.version ?? '0.0.4'
}</version>
<configuration>
<!-- for showing output of sentry-cli -->
<debugSentryCli>true</debugSentryCli>
<org>${organizationSlug}</org>
<project>${projectSlug}</project>
<!-- in case you're self hosting, provide the URL here -->
<!--<url>http://localhost:8000/</url>-->
<!-- provide your auth token via SENTRY_AUTH_TOKEN environment variable -->
<authToken>\${env.SENTRY_AUTH_TOKEN}</authToken>
</configuration>
<executions>
<execution>
<phase>generate-resources</phase>
<goals>
<goal>uploadSourceBundle</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
...
</build>
`,
},
],
},
],
]
: []),
],
additionalInfo: (
<p>
{tct(
'If you prefer to manually upload your source code to Sentry, please refer to [link:Manually Uploading Source Context].',
{
link: (
<ExternalLink href="https://docs.sentry.io/platforms/java/source-context/#manually-uploading-source-context" />
),
}
)}
</p>
),
},
{
type: StepType.CONFIGURE,
Expand Down Expand Up @@ -182,73 +292,57 @@ try {
</Fragment>
),
},
...(hasPerformance
? [
{
description: <h5>{t('Measure Performance')}</h5>,
configurations: [
{
description: t(
'You can capture transactions using the SDK. For example:'
),
language: 'kotlin',
code: `
import io.sentry.Sentry
import io.sentry.SpanStatus
// A good name for the transaction is key, to help identify what this is about
val transaction = Sentry.startTransaction("processOrderBatch()", "task")
try {
processOrderBatch()
} catch (e: Exception) {
transaction.throwable = e
transaction.status = SpanStatus.INTERNAL_ERROR
throw e
} finally {
transaction.finish();
}`,
additionalInfo: (
<p>
{tct(
'For more information about the API and automatic instrumentations included in the SDK, visit the docs.',
{
docsLink: (
<ExternalLink href="https://docs.sentry.io/platforms/java/performance/" />
),
}
)}
</p>
),
},
],
},
]
: []),
],
},
];

export const nextSteps = [
{
id: 'examples',
name: t('Examples'),
description: t('Check out our sample applications.'),
link: 'https://github.com/getsentry/sentry-java/tree/main/sentry-samples',
},
{
id: 'performance-monitoring',
name: t('Performance Monitoring'),
description: t(
'Stay ahead of latency issues and trace every slow transaction to a poor-performing API call or database query.'
),
link: 'https://docs.sentry.io/platforms/java/performance/',
},
];
// Configuration End

export function GettingStartedWithKotlin({
dsn,
sourcePackageRegistries,
projectSlug,
organization,
activeProductSelection = [],
...props
}: ModuleProps) {
const optionValues = useUrlPlatformOptions(platformOptions);
const hasPerformance = activeProductSelection.includes(
ProductSolution.PERFORMANCE_MONITORING
);

const nextStepDocs = [...nextSteps];

return (
<Layout
steps={steps({
dsn,
sourcePackageRegistries,
projectSlug: projectSlug ?? '___PROJECT_SLUG___',
organizationSlug: organization?.slug ?? '___ORG_SLUG___',
packageManager: optionValues.packageManager as PackageManager,
hasPerformance,
})}
introduction={introduction}
platformOptions={platformOptions}
nextSteps={nextStepDocs}
projectSlug={projectSlug}
{...props}
/>
);
Expand Down

0 comments on commit a562057

Please sign in to comment.