# Gradle-ის ბილდის ინსაიტები {#gradle-build-insights}

Tuist-ის Gradle პლაგინს შეუძლია ბილდის ანალიტიკა Tuist-ში გაგზავნოს, რაც საშუალებას გაძლევთ დაინახოთ ამოცანების შესრულება და ბილდის წარმადობა.

## ატვირთვის ქცევის კონფიგურაცია {#configure-upload-behavior}

ნაგულისხმევად:
- ლოკალური ბილდებისთვის ბილდის ანალიტიკა ფონურად აიტვირთება.
- CI-ს გაშვებებისთვის ბილდის ანალიტიკა წინა პლანზე აიტვირთება, რათა თავიდან ავიცილოთ ტელემეტრიის დაკარგვა ხანმოკლე აგენტებზე.

ამ ქცევის კონტროლი შეგიძლიათ `tuist` გაფართოებაში `uploadInBackground`-ის გამოყენებით:

```kotlin
tuist {
    uploadInBackground = false // always upload in the foreground
}
```

## კონფიგურაციის ცნობარი {#configuration-reference}

`tuist` გაფართოების ბლოკში `settings.gradle.kts`-ში ხელმისაწვდომია `uploadInBackground` პარამეტრი:

| პარამეტრი | ტიპი | ნაგულისხმევი | აღწერა |
| --- | --- | --- | --- |
| `uploadInBackground` | `Boolean?` | `null` (ლოკალურად — ფონურად, CI-ზე — წინა პლანზე) | ატვირთოს თუ არა ბილდის ინსაიტები ლოკალური ბილდებისთვის ფონურად. |

ეს პარამეტრი არ მოქმედებს დისტანციური ქეშის პარამეტრებზე `buildCache` ბლოკში.

## აქტორის მითითების მოთხოვნა {#report-actor-claim}

ბილდისა და ტესტების ანგარიშის მოთხოვნები მოიცავს არასავალდებულო `x-tuist-actor-id` ჰედერს მხოლოდ მაშინ, როცა ცალსახად მიანიჭებთ `TUIST_ACTOR_ID`-ს ორგანიზაციის მასშტაბის იარლიყს ან კონფიგურირებთ `buildInsights.actorId`-ს თქვენს პარამეტრებში. ნაგულისხმევად იარლიყი არ იგზავნება და პლაგინი არ აღმოაჩენს ოპერაციული სისტემის მომხმარებლის სახელებს. გარემოს გადაფარვას აქვს უპირატესობა. დააყენეთ ნებისმიერი გადაფარვა ცარიელ სტრიქონად, რათა გამოტოვოთ მოხსენებული იდენტიფიკატორი; ეს არ შლის ცალკეული სერთიფიკატებით დამყარებულ იდენტურობას. არასწორი გადაფარვები გამოტოვებენ მითითებას ნაცვლად იმისა, რომ დაუბრუნდნენ ნაგულისხმევს. თუ მორგებული პროქსი უარყოფს უცნობ ჰედერებს, გამორთეთ ისინი `TUIST_ACTOR_ID=""`-ით.

```kotlin
tuist {
    buildInsights {
        actorId = providers.environmentVariable("CORPORATE_ACTOR_ID").getOrElse("")
    }
}
```

აქტორის იდენტიფიკატორები არის 1–128 ბაიტიანი, არა-თავსაკიციანი ბეჭდვადი ASCII სიმბოლოები. ისინი ჩანს ყველასთვის, ვისაც შეუძლია ნახოს პროექტის ანგარიშები, მათ შორის საჯარო ნახვის შემთხვევაში, როცა პროექტი საჯაროა, და ექსპორტირდება ანგარიშებთან ერთად. არ ჩაწეროთ საიდუმლოები ან პირადი ინფორმაცია, რომლის გამოქვეყნებაც არ გსურთ. დადასტურებულ ინდივიდუალურ სერთიფიკატს აქვს უპირატესობა დაშბორდზე; კლიენტების მიერ გაგზავნილი იდენტიფიკატორები სხვა შემთხვევაში ცალსახად **დაუდასტურებელია**. ისინი არასდროს ანიჭებენ ნებართვებს და არ აკავშირებენ ავტომატურად Tuist-ის მომხმარებელთან. ძველი სერვერები იგნორირებენ მითითების ჰედერს, ხოლო ახალი სერვერები განაგრძობენ ძველი კლიენტების მიღებას მის გარეშე. ახალი საერთო-ტოკენის ანგარიშები იდენტიფიკატორის გარეშე აჩვენებენ **უცნობს**, გამომქვეყნებელი ორგანიზაციის ნაცვლად; ისტორიულ ანგარიშებს ინარჩუნებენ წინა მითითებას. ბილდებისა და ტესტების სიები გამოყოფენ დადასტურებული მომხმარებლის ფილტრებს დაუდასტურებელი მოხსენებული იდენტიფიკატორის ფილტრებისგან.

## ქსელის ნდობით გამოქვეყნება {#network-trusted-publishing}

თვითმასპინძლობით განლაგებებს შეუძლიათ ცალსახად დაუშვან Gradle-ის ბილდისა და ტესტების ანგარიშები მათი სანდო ქსელიდან დეველოპერის სერთიფიკატების გარეშე. ოპერატორმა უნდა კონფიგურირებაში `TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS=true` ინსტანციაზე და თავიდან გადატვირთოს ის. ეს ვრცელდება ყველა მხარდაჭერილ პროექტზე; დაშბორდზე პარამეტრი არ არსებობს. იხილეთ <.localized_link href="/guides/server/self-host/server#network-trusted-access">თვითმასპინძლობის სახელმძღვანელო</.localized_link>.

დანიშნულების ადგილი ერთხელ კონფიგურირეთ რეპოზიტორიაში:

```kotlin
tuist {
    project = "organization/project"
    url = "https://tuist.internal.example"
    buildCache { enabled = false }
}
```

ბილდისა და ტესტების ანგარიშგება არ საჭიროებს ავთენტიფიცირებულ ქეშის ენდპოინტის აღმოჩენას. გამორთეთ ქეში, თუ ინსტანცია ცალკე არ ააქტიურებს ქსელის ნდობით ქეშზე წვდომას ან დეველოპერები არ ამზადებენ ტოკენებს. ხელმოუწერი ტესტების ანგარიშები გამოტოვებენ shard-ისა და არსებული ბილდის მითითებებს და არ ამუშავებენ კარანტინის ან ფლაკინგის ავტომატიზაციებს. კარანტინის ძიება გამოტოვებულია, როცა სერთიფიკატები ნამდვილად არ არსებობს; მოქმედი სერთიფიკატებით ინარჩუნება არსებული ავთენტიფიცირებული ქცევა. თუ სერთიფიკატები არსებობს, ისინი მაინც გამოიყენება და არასწორი სერთიფიკატები იწვევს შეცდომას ნაცვლად იმისა, რომ დაუბრუნდნენ სერთიფიკატების გარეშე გამოქვეყნებას. როცა სერთიფიკატები არ არსებობს, პლაგინი ავტომატურად აღმოაჩენს, ნებას აძლევს თუ არა თვითმასპინძლობითი სერვერი სერთიფიკატების გარეშე ანგარიშგებას. არ არის საჭირო არც კლიენტის ფლაგი და არც `buildInsights` პარამეტრი. განაახლეთ ყველა სერვერის რეპლიკა აღმოჩენის შესაძლებლობის მქონე ვერსიამდე სერთიფიკატების გარეშე კლიენტების განახლებამდე. უფრო ძველ სერვერებს აღმოჩენის გარეშე, გამორთულ ინსტანციებს და აღმოჩენის შეცდომებს კვლავ სჭირდებათ ავთენტიფიკაცია; ავთენტიფიცირებული გამოქვეყნება რჩება თავსებადი. ცალსახად ცარიელი `TUIST_TOKEN` იწვევს შეცდომას ნაცვლად იმისა, რომ ჩართოს სერთიფიკატების გარეშე გამოქვეყნება. ფორკის ან Dependabot-ის ჯობებისთვის საიდუმლოების გარეშე, წაშალეთ ეს ცვლადი ნაცვლად იმისა, რომ განსაზღვროთ როგორც ცარიელი სტრიქონი.

სერვერი ანიჭებს სერთიფიკატების გარეშე ანგარიშის ID-ებს. წარდგენის გამეორებამ შეიძლება შექმნას მეორე ანგარიში; ეს რეჟიმი არ იძლევა იდემპოტენტური განმეორებების ან ავთენტიფიცირებულ ტესტების ანგარიშებთან კორელაციის გარანტიას. ასეთ ანგარიშებს არ შეუძლიათ VCS კომენტარების ან ავტომატური შეცდომის-აგენტის მოვლენების გამოწვევა. ქსელზე წვდომა არის გამოქვეყნების ნდობის საზღვარი, არა მოხსენებული აქტორის იდენტურობის დადასტურება.

## მორგებული მეტამონაცემები {#custom-metadata}

მიამაგრეთ ტეგები და გასაღები-მნიშვნელობის მონაცემები Gradle-ის ბილდებს, რათა შეადაროთ გაშვებები სხვადასხვა გუნდების, აპარატურის ან სამუშაო ნაკადების მიხედვით. ტეგები ხელმისაწვდომია დაშბორდის ფილტრებში, ხოლო მნიშვნელობები ჩანს თითოეული ბილდის დეტალურ გვერდზე და API-სა და Model Context Protocol ინსტრუმენტებში.

დააყენეთ მეტამონაცემები გარემოს ცვლადებით:

```sh
export TUIST_BUILD_TAGS="nightly,android"
export TUIST_BUILD_VALUE_TICKET="TUIST-123"
export TUIST_BUILD_VALUE_RUNNER="macos-14"
```

ასევე შეგიძლიათ კონფიგურირება მეტამონაცემების `settings.gradle.kts`-ში:

```kotlin
tuist {
    buildInsights {
        tag("nightly")
        tag("android")
        value("ticket", "TUIST-123")
        value("runner", "macos-14")
    }
}
```

როცა ერთი და იგივე მნიშვნელობა კონფიგურირებულია ორივე ადგილას, უპირატესობა აქვს `settings.gradle.kts`-ში მითითებულ მნიშვნელობას.

ტეგები უნდა შეიცავდნენ მხოლოდ ასოებს, რიცხვებს, დეფისებს და ქვედა ტირეებს. ბილდს შეიძლება ჰქონდეს მაქსიმუმ 50 ტეგი და თითოეულ ტეგს შეიძლება ჰქონდეს მაქსიმუმ 50 სიმბოლო. ბილდს შეიძლება ჰქონდეს მაქსიმუმ 20 გასაღები-მნიშვნელობის ჩანაწერი, თითოეულ გასაღებს შეიძლება ჰქონდეს მაქსიმუმ 50 სიმბოლო და თითოეულ მნიშვნელობას შეიძლება ჰქონდეს მაქსიმუმ 500 სიმბოლო. ეს იგივე სერვერის მხარის ლიმიტებია, რომლებიც გამოიყენება Xcode-ის ბილდის მეტამონაცემებისთვის. პლაგინი გამოტოვებს არასწორ ტეგებსა და ზედმეტად დიდ ან ცარიელ მეტამონაცემების ჩანაწერებს ანგარიშის გაგზავნამდე, ასე რომ არასწორმა კონფიგურაციამ ვერ შეუშლის ხელი ბილდის ინსაიტების ანგარიშის დანარჩენი ნაწილის შენახვას. გამოიყენეთ გასაღები-მნიშვნელობის მეტამონაცემები იმ მნიშვნელობებისთვის, რომლებიც არ აკმაყოფილებენ ტეგის შეზღუდვას.

მორგებული მეტამონაცემები ჩანს პროექტის წევრებისთვის დაშბორდზე და API-სა და Model Context Protocol ინსტრუმენტების საშუალებით. არ გამოიყენოთ ის სერთიფიკატების, წვდომის ტოკენების ან სხვა მგრძნობიარე მონაცემებისთვის. Tuist ინახავს Gradle-ის ბილდის მონაცემებს, ამ მეტამონაცემების ჩათვლით, 90 დღის განმავლობაში. დეტალებისთვის იხილეთ <.localized_link href="/guides/server/data-retention">მონაცემთა შენახვის პოლიტიკა</.localized_link>.

## შეცდომის დეტალები {#failure-details}

როდესაც ბილდი ვერ ხერხდება, პლაგინი იუწყება, რატომ ჩაიშალა თითოეული წარუმატებელი ამოცანა ან კონფიგურაციის ნაბიჯი: გამონაკლისის შეტყობინება და მისი მიზეზთა ჯაჭვი, როგორც Gradle-ის კონსოლი ბეჭდავს, მაგალითად, ჩავარდნილი `compileJava` ამოცანის კომპილატორის შეცდომები ან შეცდომა ბილდის სკრიპტში. სტეკის ტრასირებები და ამოცანის გამოტანა არ გროვდება. პლაგინი პროექტის შიგნით არსებულ გზებს ფარდობითად აქცევს ანგარიშის გაგზავნამდე, ხოლო Tuist ფარავს სერთიფიკატებს და სხვა ცნობილ ადგილობრივ გზებს. თითოეული შეტყობინება შემოიფარგლება 16 KiB-ით, ხოლო ბილდი ინახავს მაქსიმუმ 32 ჩავარდნილი ნაბიჯის შეტყობინებებს.

შეცდომის შეტყობინებები ჩანს პროექტის წევრებისთვის API-ს, Model Context Protocol ინსტრუმენტების (`get_gradle_build`, `list_gradle_build_tasks` და `get_gradle_build_step`) და CLI-ს საშუალებით:

```bash
tuist build gradle failure list <build-id>
```

შეტყობინებები შეიძლება შეიცავდნენ კოდის ფრაგმენტებს და პროექტის დეტალებს. ანგარიშები, რომლებიც ქვეყნდება სერთიფიკატების გარეშე [ქსელის სანდოობაზე დაფუძნებული გამოქვეყნების](#network-trusted-publishing) მეშვეობით, არ შეიცავენ მათ. Tuist ინახავს მათ Gradle-ის ბილდის დანარჩენ მონაცემებთან ერთად 90 დღის განმავლობაში.
